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Your Instructors This Week 

Ydur^iex^werSrand lab assist3nts throughout this course will be some 
coml3ln:atibin:of those listed below. Please feel free to ask questions. If you 
have any commentscQf suggestions about the course structure or content, 
please message Debbie at the e-mail address listed below. (E<mail messages 
help us keep track of all tbmrrierits.) 

Debbie MacKayy - <Mactc:ay:OSBU North:Xerox> 

Mark Hahn 

Leslie Kanno 
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Goal of this Cliass 

This class covers ViewPoint programming topics that are co^rBsidrered:} 
"advanced," which refers to subjects that are either more difficyltdtof 
understand or are harder to find documentation on (or both); v c 

After this class, you should be able to implement Selection and tlf^^ 
managers, interact programmatically with documents, and improve the 
performance of your applications through program Optimization:.: ^ 
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Pre-requisites 



This clas$ is geared for the seasoned programmer who is already familiar 
with, programming in the ViewPoint environment/Thorough knowledge of 
Mesa is assumed; in addition, you should also be fa miliar with the common 
Viewpoint interfaces (e.g., Attention, Containee, Display, FormWindow, 
MehuOata, StarWindowShell, Window, XFormat, XString, et al). This class 
will be very difficult for you without a basic understanding of the 
environment. 
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We're Not Your Mother 

The general format of the class is lecture in the mornlhg, lab th% 
afternoon. The lab has no format: you are expected to complete fbiir 
assignments (or at least try) but you can come and go as you wish. ' 

Major No-No: Don't leave for three hours in the middle of the afternoon 
and then come back and expect us to stay here with you until 10 PM. 
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Day 1 : TIP 
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TIP (Terminal Interface Package) provides a mechanism to translate user's 
keyboard and mouse actions into client program actions. TIP must direct 
user input to one of the windows on the display and notify the program 
that implements that window's functionality. 

This notification is accomplished by two processes, the Stimulus and 
Notifier. The Stimulus is a high-priority process that watches for keyboard 
and mouse actions; it queues these events for the Notifier process. The 
Notifier dequeues each event and associates it with a window. After 
determining the correct window for a user action, the Notifier searches for 
the action in a set of TIP tables. If the action is found, the Notifier passes the 
corresponding list of results to the window's underlying application via its 
NotifyProc. The application can then perform the appropriate actions in 
response. 
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User presses keyboard key or mouse button 



Stimulus process enqueues the action 



Notifier: 

• dequeues action 

• determines which window the action is for 

• searches TIP tables for the action 

• if the action is found, call the window's 
NotifyProc; otherwise, ignore the action 



NotifyProc act on results 



Client 
Program 
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Tables 

The first thing the Notifier process does, after determining which window 
the user's action is for, is locate the hardware action in a TIP table, TIP tables 
are structured much like Mesa SELECT statements. The left hand side of the 
table contains the hardware actions and the right hand side contains a list of 
results that will be passed to the application's NotifyProc. 

SELECT TRIGGER FROM 
Point Down *> 

SELECT ENABLE FROM 

LeftShift Down -> COORDS, ShiftedPoint; 
ENOCASE«> COORDS, PointCUck; 
Adjust Down COORDS, AdjustDown; 
ENDCASE... 

OR 

SELECT TRIGGER FROM 
S Down => TurnLeft; 
D Down => TurnRight; 
K Down => Forward; 
L Down -> COORDS, Fire; 
ENDCASE... 
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TRIGGER and ENABLE Statements 

TRIGGER statements check the next action from the Notifier's input queue 
and branch to the appropriate choice. 

ENABLE statements indicate the current condition of the keyboard or 
mouse. 

TRIGGER terms can appear in sequence, separated by ANDs and can be 
mixed with ENABLE terms separated by WHILES. The complete syntax of TIP 
tables can be found in the ViewPoint Programmer's Manual. 

SELECT TRIGGER FROM 

V Down AND D u/ => COORDS, Penicinin; 

DELETE Down WHILE NEXT Down => Del eteNextOb ject ; 

ENDCASE 

This Statement could be read, "V goes down and then D goes up with no 
other actions in between". The next statement would match if the DELETE 
key goes down while the NEXT key is down. 
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Mouse Actions and Timeouts 

You can recognize other useful actions in TIP tables such as mouse motion 
and when the mouse enters or exits a body window. In this example, note 
that the action is the mouse moving and the static condition is that the Point 
button is held down. 

SELECT TRIGGER FROM 

MOUSE => SELECT ENABLE FROM 

Point Down => COORDS, PointMotion; 
ENDCASE => COORDS, Mouse; 
EXIT => COORDS, Exit; 
ENTER => COORDS, Enter; 
ENDCASE... 

You can also specify timeout conditions for user actions. A timeout 
following a trigger indicates a timing condition that must hold between this 
trigger and its predecessor. Timeouts are in milliseconds. 

SELECT TRIGGER FROM 
Point Down => 

SELECT TRIGGER FROM 

Point Up BEFORE 200 AND 

Point Down BEFORE 200 »> COORDS. Doubled ick; 
Adjust Down BEFORE 300 »> COORDS, Poi ntAndAdJust ; 
ENDCASE «> COORDS, PointDown; 
Adjust Down »> COORDS, AdjustDown; 
ENDCASE. . . 
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Creating a Private TIP Table 

Viewpoint supplies a chjain of default TIP tables that your program can use. 
If you want to recognize additional actions, you can create a private TIP 
table or a private chain of tables for a particular application. Integrating a 
private TIP table requires that you first create a table, and then put that 
table into the system's chain of tables. You will see how to insert tables 
later; for now we will concentrate on creating tables with TlP.Createlable. 

TlP.Createlable: PROCEDURE[ 
file: XStn'ng .Reader, 
z: UNCOUNTED ZONE NIL. 
contents: XString . Reader ^ NIL] 
RETURNS[table: TIP. Table]; 

TIP. Table: TYPE 
TIP.TableObject: 



= LONG POINTER TO TIP.TableObject; 
TYPE; 
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Creating and Destroying Private TIP Tables (example) 

table: TIP.Table NIL; 

CreateTIPTable: PROC « { 
fneName:XStr1ng.ReaderBody ^ XStr1ng.FroniSTRING{ "Prog.TIP"Ll ; 
contents: XString.ReaderBody XString.FromSTRINGl" 
SELECT TRIGGER FROM . 

S Down *> TurnLeft; . 

D Down => TurnRlght; V ^"^""^ 

K Down => Forward; , Vs^ 

L Down a> Fire; 
ENDCASE... ^ o.*^^"^ 

"LI; . 
table TIP.CreateTable( ^'c^^^ 

file: ^fileName, ^ 

contents: ©contents! TIP.InvalidTable => RESUME]; 
IF table =*NIL THEN { 

mh: XMessage.HandU « Oefs.GetMessageHandlel 1 ; 

msg: XString.ReaderBody XMessage.Get(mh, Defs.kbadSyntax] ; 

Attent i on . Post ( @nisg 1 } 1 ; 

}; 

- Destroy the specified TIP table 

DestroyTable: PROC = {TIP.DestroyTable{@tablel}; 
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Placeholders 

Viewpoint provides a chain of empty tables called Placeholders. When the 
system is booted, a set of normal tables is installed; these tables contain all 
the basic key actions that most applications need. 



Placeholders 



mouseActions 



keyOverrides 



softKeys 



keyboardSpecific 



blackKeys 



sideKeys 



backstopSpecialFocus 



NIL 



System TIP Tables 



NormalMouse.TIP 

i 



NormalSoftKeys.TIP 

i 



NormalKeyboard.TIP 

i 



NormalSldeKeys.TIP 

i 



NormalBackstop.TIP 
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TIPStar 



The TIPStar interface provides procedures for manipulating the chain of TIP 
tables. Tables can be installed or removed from the chain of existing tables. 
It is often desirable to install a private table when the user clicks Point in an 
application's body window; similarly, the table can be removed when the 
mouse exits the window. In this fashion, your application can have special 
interpretations for actions and not affect other applications. 



TIPStar. Placeholder: TYPE = { 

mouseActions, keyOverrides , softKeys, iceyboardSpedf ic, 
blaclcKeys, sideKeys, baclcstopSpeclal Focus}; 



SetUpTipTable: PUBLIC PROClbody: Window. Handle] = { 
fileName: XString.ReaderBody ^ XString.FroinSTRING[ "Prog.TIP"L] ; 
contents: XString.ReaderBody * XString.FromSTRING( " 
SELECT TRIGGER FROM 
S Down => TurnLeft; 
D Down TurnRight; 
ENDCASE... 
"Lj; 

table *- TIP.CreateTablef...]}; 

MyNotifyProc: TIP.NotifyProc - C 

FOR input: TIP. Results results, input. next UNTIL input « NIL DO 
WITH z: input SELECT FROM 
atom => 

SELECT z.a FROM 
pointDown IF NOT pushed THEN [ 

TIPStar. PushTablefblackKeys, table] ; 
TIP.SetlnputFocuslw: window, takeslnput: TRUE]; 
pushed TRUE}; 
exit «> IF pushed THEN { 

TIPStar. PopTable I blackKeys, table] ; 
pushed ^ FALSE}; 
turnLeft *> Defs.TurnLeft(goodGuy, window]; 
turnRight »> Defs.TurnRight(goodGuy, window]; 
ENDCASE; 
ENDCASE ; - WITH 2: input 
ENDLOOP}; 
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Pushing and Popping Tables 

Let's examine the effects of clicking Point and EXITing the body window in 
the previous example. Clicking Point in the body window pushes a private 
TIP table, which passes the atom TurnLeft when the key S is pressed and the 
atom TurnRight when the D key is pressed. If a private table were not 
inserted into the chain of tables, a text character would have been passed to 
whichever window had the input focus. 

When the mouse EXITs the body window, Prog.TIP is popped off the chain 
and the keys S and D go back to their normal interpretation. 



Placeholders 



TIP Tables 



keyboardSpecific 



Prog.TIP is inserted (Pushed) directly after 
the specified placeholder; actions not found 
in Prog.TIP may be found in later. tables. 



blackKeys 



Prog.TIP 





r 


NormalKeyboard.TlP 



sIdeKeys 
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Storing Tables 

You can also replace ail tables following a placeholder with a new TIP 
table(s) by calling TiPStar.storeTabie. StoreTable returns the replaced 
table(s) so the client can restore them later. 

TIPStap. StoreTable: PROCEDURE[TIPStap. Placeholder, TIP. Table] 
RETURNS[TIP. Table]: 

Before NewTable.TlP stored 

i 

blackKeys ^ 

Prog.TIP 



sideKeys 



NormalKeyboard.TIP 

f 



Both Prog.TIP and NormalKeyboard.TIP have been replaced by NewTable.TlP 



blackKeys 



sideKeys 



NewTable.TlP 
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Results Lists 



After the Notifier has found a user action in a TIP table, it passes the results 
on the RHS of the table to the application's NotifyProc. It is then up to the 
NotifyProc to interpret the results and perform the desired actions. The 
results are in the form of a linked list of variant records. 

TIP. Results: TYPE = LONG POINTER TO 
— READONLY— TIP . ResuUOb ject ; 

TIP.ResultObject: TYPE » RECORD[ 

next: TIP. Results, 

body: SELECT type: * FROM 

atom => [a: ATOM], " constant in table 

bufferedChar => NULL, -notseenbyNotifyProcs 
coords -> [place: Window. PI ace] , -window re/atiVe 
int => [i: LONG INTEGER], - constant in table 

key => [key: KeyName, downUp: OownUp], 
nop => NULL, not seen by NotifyProcs 

String => [rb: XSt r i ng . ReaderBody],- cy)arorcon5tant 



time => [time: System. Pul ses] , 
ENDCASE]; 




NIL 



atom: PointOown 
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Atoms 

An atom is a one-word object that corresponds to a textual string. By 
passing atoms, objects may be named textually without paying the expense 
of actually storing, copying, and comparing the strings themselves. TIP 
tables often contain text strings that correspond to atoms on their right 
hand sides; these strings are converted into one word atoms and are passed 
into the clients NotifyProcs as atom variants. 

Your application must declare atoms that correspond exactly to the ones in 
the TIP tables. You create an atom by calling Atom. MakeA torn, passing a Mesa 
string that is equivalent to the one in the TIP table. 

Atom, ATOM: TYPE[1]; 

Atom. null: ATOM = LOOPHOLE[0]; 

Atom.MakeAtom: PROCEDURE[pName: LONG STRING] 
RETURNS[atom: Atom. ATOM]; 
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NotifyProcs 

The NotifyProc interprets only those results it is interested in and ignores the 
rest. Typically, the NotifyProc will use the results to modify the application's 
data and to call various procedures. 



mouse, pointMotion, enter, exit, delete: Atom. ATOM Atom. null; 

InitAtoms: PROC = [ 

mouse * Atom.MakeAtom f "Mouse"L] ; 

pointMotion * Atom.MakeAtom("PointMotion"Ll ; 
... 

}; 

MyNotifyProc: TIP. NotifyProc = [ 
<< [window: Window. Handle, results: ResultsJ>> 
data: Defs.Data Defs.GetContext (window ] ; 

FOR input: TIP. Results results, input. next UNTIL input = NIL 00 
WITH z: input SELECT FROM 
coords -> data. pi ace * z. place ; 
atom => 

SELECT z^ FROM 

mouse => IF data.lastMouse - neither THEN OisplayBitmap{window,data] 

ELSE PointMotion (window, data]; 
pointMotion -> PointMotion (window, data]; 
enter => EnterWindow [window, data]; 
exit a> Ex itW1ndow[ window, data]; 
delete => Defs.Delete[window, data]; 
ENDCASE; 
ENDCASE ; - WITH z: input 
END LOOP; 

}; 
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NotifyProcs (cont'd) 



You can associate your NotifyProc with a chain of TIP tables by calling 
TIP.SetTableAndNotifyProc; this would usually follow the table creation 
code. The Notifier will check your table before searching the default 
NormalKeyboard.TIP table. If you push your table, ALL applications 
will "see" this table, so you must pop the table before other applications are 
invoked. 



The call to TiPStar.NorraalTable returns the table at the head of the chain 
of TIP tables; this is the appropriate table to use when calling 
SetTableAndNotifyProc. StarWindowShell.CreateBody will implicitly make 
this call to SetTableAndNotifyProc. 

SetUpTIPTable: PROClbody: Window. Hand! ej^ { 
table TIP.CreateTablel...!; 
TIPStar.PushTable [blackKeys, table 1; 
TIP.SetTableAndNotifyProc [ 
window: body, 

table: TIPStar.NornialTable[ ] , 
notify: MyNotifyProcl ; 

}; 



Day 1: TIP 



Advanced Viewpoint Programming Class 



- February, 1988 



1-18 



Input Focus 

Mouse actions are typically sent to the window containing the cursor, but 
keystrokes are sent to the window containing the input focus. Since you will 
often want to interpret keystrokes, you will need to know how to set the 
input focus. Other applications will take the the input focus after the cursor 
leaves your body window (i.e. when the user selects an icon). 

TIP.SetlnputFocus: PROCEOURE[ 
w: Window. Handle, 
takeslnput: BOOLEAN. 

newInputFocus: TIP. LoslngFocusProc ^ NIL. 
clientOata: LONG POINTER ^ NIL]; 

TIP. LoslngFocusProc: TYPE = PROCEDURE[ 
w: Windovf. Handle. data:LONG POINTER]; 



MyNotifyProc: TIP.NotifyProc = C 
data: Defs.Data 6etContext[winclow] ; 

FOR input: TIP. Results results, input. next UNTIL input « NIL DO 
WITH z: input SELECT FROM 
atom => SELECT z.a FROM 
pointDown «> {TIPStar.PushTable [blackKeys, table]; 
TIP.SetlnputFocus f 
w: window, 
takes Input: FALSE, 
newInputFocus: LostlnputFocus, 
clientOata: data]}; 

• • • 

}; 

LostlnputFocus: TIP.LosingFocusProc = [ 
< <PROC[w: Window.Handte, data: LONG POINTER] > > 
< < perform actions when window loses input focus > > 

}; 
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Periodic Notification 

You may have a background process that needs to perform some operation 
in the Notifier process (such as obtaining the current selection). If your 
program was not running in the Notifier, then the user, or some other 
application, could change the current selection in the middle of your 
operation. By calling TIP.CreatePeriodicNotify, you can have your 
NotifyProc called at set intervals from within the Notifier process. 

When you no longer need to be notified, you can cancel the periodic 
notification mechanism. 

TIP.PeriodicNotify: TYPE[1]; 

TIP.CreatePeriodicNotify: PROC[ 
window: Window. Handle* 
results: TIP. Results, 
milliseconds: CARDINAL, 
notifyProc: TIP .NotifyProc NIL] 
RETURNS[TIP.PeriodicNotify]: 

TIP. Cancel Per iodicNot if y: PROC[TIP. PeriodicNotify] 
RETURNS[null : TIP.PeriodicNotify]; 
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Periodic Notification (cont'd) 

This sample code registers a NotifyProc that displays the current time every 
second. While this type of operation does not need to be performed in the 
Notif ier, it is simple to understand. 



results: TIP.ResultObject; 

per1od1cNot1fy: TIP.PeriodicNotlfy * TIP.nunPeriodicNotify; 
g1oba1Place: Window. Place; 

MyHotifyProc: TIP. NotifyProc » { 

FOR input: TIP. Results *■ results, input. next UNTIL input * NIL DO 
WITH z: input SELECT FROM 
atom => SELECT z.a FROM 
currTime => C 
rb: XString.ReaderBody * GetCurrentTime{ ] ; 
[] SimpleTextOisplay.StringlntoWindowistring: @rb,...]}; 
ENDCASE; 
ENDCASE ; WITH z: input 
ENDLOOP; 

}; 

77ie "results" object must continue to exist after the call to 
CreatePeriodicNotify or the terrible things will happen. 
StartTime: MenuData.MenuProc = { 
results [next: NIL, body: atom(a: currTimell; 
periodicNotify * TIP. CreatePer i od i cNot i f v f 

window: StarWindowShel 1 .GetBody [ [window] 1 , 

results: ©results, 

milliseconds: 1000, 

notifyProc: MyNotifyProcJ ; 

}; 

StopTlme: MenuData.MenuProc = { 
periodicNotify * TIP. Cancel Per i odi cNot i f y f peri odi cNot i f y I : 

}; 
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Managers 

TIP managers are used to send all user input through a specified table and 
NotifyProc rather than through the window containing the cursor or input 
focus. Managers, in effect, override the normal behavior of the system and 
are usually in use for only a short time. For example, an application that 
wishes to capture a bitmap image of the root window might create a 
manager to avoid having objects selected during the capture. 

TIP. Manager: TYPE = RECORDf 
table: TIP. Table, 
window: Window. Handle, 
notify: TIP. NotifyProc] ; 

TIP.GetManager: PROCEDURE RETURNS[current : TIP. Manager] ; 

TIP.ClearManager: PROCEDURE = INLINE 

TIP.SetManager: PROCEDURE[new: TIP. Manager] 
RETURNS[old: TIP .Manager] ; 
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Manager Example 

This example contains excerpts from a program that copies a bitmap from 
the display. If no manager were used, MyNotifyProc would not be called for 
actions that occured over another window. 

MyManager, Old: TIP. Manager * TIP. null Manager; 
table: TIP. Table ^ InitTablell; 

MyNotifyProc: TIP.NotifyProc = ( 
place: Window. Place; 

FOR input: TIP. Results *■ results, input. next UNTIL input - NIL DO 
WITH z: input SELECT FROM 
coords -> place * z. pi ace; 
atom =»> SELECT z.a FROM 
confirm «> ConfirmBoxl window, place); 
start *> StartBox( window, place); 
ENDCASE; 
ENDCASE; - WITH z: input 
ENOLOOP; 

}; 

~ Called to invoke the manager 
start: MenuData.MenuProc = { 

body: Window. Handle StarWindowShell .6etBody[ [window] ] ; 

MyManager [table: table, window: body, notify: MyNotifyProc]; 

Old * TIP. Se tManaqer [ new : MyManager); 

}; 

— Saves the upper left comer to the box 

StartBox: PROC [window: Window. Handle, place: Window. Place] * ( 
data: Defs.Data Defs.GetContext[window] ; 
data.upperLHCorner place; 

}; 

- Copies the bitmap specified by the upper left corner and the current position 
ConflrraBox: PROC[window:Window. Handle, place: Window. Place] - { 

CopyBitmap[ window, place); 
[ ) *• TIP.SetManaqerfnew: Old) ; 

}; 
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Call-Back Notification 

Call-back notification is similar to having a manager except that the client's 
call stack is not unwound. All input that matches the client's TIP table is 
directed to the TIP.CallBaclcNotifyProc. 

TIP. Call Back: PROCEDURE[ 
window: Window. Handle, 
table: TIP. Table, 
notify: TIP.Cal IBackNotifyProc] ; 

TIP.CallBaclcNotifyProc: TYPE = PROCEDURE[ 
window: Wi ndow. Handl e , results: TIP. Results] 
RETURNS[done: BOOLEAN]; 



Manager 



Notifier 



Notifier 



SetManager 



Manager's 
NotifyProc 



Reset Manager 



Call Back 



Notifier 



CallBack 



CaliBackNotifyProc 



Return done = TRUE 



Comparison of Managers and Call-Back Notification 
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Call-Back Notification Example 



MyNotifyProc is associated with the application's body window and starts 
the call-back notification when the user clicks Point. The Start procedure 
does not return until the cancel or confirm atom is encountered and the 
TIP.CallBackNotifyPpoc returns TRUE. 



MyNotifyProc: TIP.NotifyProc = { 

FOR input: TIP. Results results, input. next UNTIL input = NIL DO 
WITH z: input SELECT FROM 
atom *> SELECT z.a FROM 

point => start ( wi ndow ] ; 
ENDCASE; 
ENDCASE ; - WITH z: input 
ENDLOOP; 

}; 

MyCanBackNotifyProc: TIP. Call BackNotifyProc = { 

FOR input: TIP. Results results, input. next UNTIL input = NIL DO 
WITH z: input SELECT FROM 
atom SELECT z.a FROM 
start -> StartBox(window,TIP.GetPlace[StarOesktop.GetWinclow( ] ] ] ; 
confirm => (Conf 1rmBox[window,TIP.GetPlace{StarOesktop.GetWindow[ ] ] ] ; 

RETURN f TRUE U ; 
cancel => { Cancel Box (wi ndow ] ; RETURN [TRUE 1 1: 
ENDCASE; 
ENDCASE ; - WITH z: input 
ENDLOOP; 
RETURN f FALSE] : 

}; 

start: PROCIwindow:Window. Handle] =* C 
TIP. Call Back [window; window, table: table, notify: MyCal 1 BackNotifyProc J ; 
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User Abort 

There are two methods in which your program can recognize the user 
pressing the STOP key: notification by call-backs or by checking an abort bit. 
The advantage of call-back procs is that you don't have to keep checking the 
abort bit; however, the call-back proc must be able to stop the application. 
By polling the abort bit, you will be able to stop the process more easily at 
the cost of higher overhead. We will discuss call-backs first. 

TIP.SetAttention: PROCEDURE[ 

Window. Handle, attention: TIP. AttentionProc] ; 
TIP.AttentionPpoc: TYPE » PROCEDURE[window: Window. Hand! e] ; 

continue: BOOLEAN FALSE; 

Count: PROCEDURE [...1 = { 
WHILE continue 00 
<< do some work > > 

END LOOP}; 

~ This proc is called when the user presses the STOP key 
MyAttentionProc: TIP. AttentionProc = {continue FALSE}; 

- Begin recognizing user aborts with a call- back proc 
SetAttention: PROClbody: Window. Hand! el « { 
TI P . SetAttent i on f wi ndow; body, attention: MyAttentionProc]}; 

Start: MenuData. Menu Proc - [ 
continue TRUE; 

Process. Detach [ FORK Count I ...]]} ; 
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User Abort (cont'd) 



Here's another version of the tool that uses polling instead of call-backs. 
You can programmatically reset the abort bit; otherwise, it is reset with the 
next keystroke. 



— This procedure must periodically call the UserAbort procedure 
Count: PROCEDURE I body: Window. Handle] « { 

WHILE NOT TIP. UserAbort f body I DO 

<< do some work > > 
ENDLOOP; 

}; 

- Set user abort flag for the window to FALSE 
ResetAbort: MenuOata.MenuProc = ( 

body: Window. Handle S tarWindowShe 11 .GetBody[ (window! 1 ; • 

TIP. ResetUserAbortf body 1 : 

}; 

" Eftable user aborts for specified window 
SetAbort: MenuOata.MenuProc « C 

body: Window. Handle StarWi ndowShe 11 .GetBody( [window] ] ; 

TIP.SetUserAbortf body] ; 

}; 

Start: MenuOata.MenuProc = C 
Process.Detach(FORK CountfStarWindowShell .GetBodyl (window] ] ] ] ; 
}; 
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Character Translation 

When any of the black keys on the keyboard are pressed, the result 
generated by the system Normal Keyboard . TIP table is a BUFFEREDCHAR. If you 
want to construct a character from this keystroke, you will need to write a 
character translator procedure. A character translator is a call-back proc that 
is called by TIP whenever a result of type BUFFEREDCHAR is encountered, and 
it can map the key to whatever character the client chooses. 

TIP.CharTranslator: TYPE » RECORD[ 
proc: TIP.KeyToCharProc, 
data: LONG POINTER]; 

TIP.KeyToCharProc: TYPE = PROCEDURE[ 
keys: LONG POINTER TO TIP.KeyBits, 
key: TIP.KeyName. 
downUp: TIP.DownUp, 
data: LONG POINTER, 
buffer: XString .Writer] ; 

TIP.KeyBits: TYPE « Level IVKeys . KeyB its ; 
Level IVKeys.KeyBits: TYPE = 

PACKED ARRAY Level IVKeys . KeyName OF Level IVKeys. DownUp ; 
Level IVKeys. DownUp - KeyboardWindow. Keystations. DownUp; 

TIP.KeyName: TYPE = Level IVKeys. KeyName; 
Level IVKeys. KeyName: TYPE = MACHINE DEPENDENT { 
— Four, Six, E. Seven,...}; 

TIP.SetCharTranslator: PROCEDURE[ 
table:^ TIP. Table, 
new: CharTranslator] 
RETURNS[old: CharTranslator]; 
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Character Translation (cont'd) 

In order to translate a BUFFEREDCHAR you must either map the current key 
pressed (key) or use the current state of the keyboard (determined by the 
value keys) to determine what character to generate. If you only want to 
map the current key, all you need to do is perform a simple translation 
between the enumerated value key, and the desired character in some 
character set. If you want to take into account multiple key positions (e.g. 
PROP 'S down and Q down) then you will have to use the keys argument. 

After generating a character(s) within your TiP.KeyToCharProc, you should 
append them to the buffer passed in. The buffer will be passed to your 
TiP.MotifyProc, as a string variant, at which time it can be added to the 
data structure of your application. 

SomeKeyToCharProc: TiP.KeyToCharProc = [ 

< <keys: LONG POINTER TO TIP.KeyBits,...buffer: XString.Writer]> > 

char: XChar. Character; 

code: XCharSetO.CodesO; 

IF kevs fLeftShiftl = down OR keyslRightShiftJ = down THEN 
code * SELECT key FROM 
A => upperA, 

• • • 

ENDCASE *> upperZ 

ELSE 

code * SELECT key FROM 
A -> lower A, 

ENOCASE «> lowerZ; 
char ^ XCharSetO. Make ( code 1; 
XStrinq.AppendCharf buffer, charl ; 
H 
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Character Translation Example 



oldTrans: TIP.CharTranslator (proc: NIL, data: NILJ; 

MyKeyToCharProc: TIP.KeyToCharProc = { 

< <keys: LONG POINTER TO TlP.KeyBits,...buffer: XString.Writer] > > 
code: XCharSetO.CodesO SELECT key FROM 

A => upper A, 
• • • 

ENDCASE =»> upperZ; 
char: XChar. Character *■ XCharSetO, Make ( code ] ; 
XStrinq.AppendCharf buffer, char] ; 

}; 

MotifyProc: TIP.NotifyProc = { 

< < PROClwindow: Window. Handle, results: TIP. Results] > > 
data: Defs.Oata Defs.GetContextlwindow] ; 

FOR input: TIP. Results results. Input. next UNTIL input - NIL DO 
WITH z: input SELECT FROM 
string => { 

XStrinq.AppendReaderfto: @data.wb« from: 02. rb ! 
XString, Insuff icientRoom => { 
XString.ExpandWriter[w: @data.wb, extra: 20]; RETRY}]; 
D i sp 1 ay Text ( wi ndow ] } ; 
atom =:> SELECT z.a FROM 
enter Enter (wi ndow ] ; 
exit => Exitlwindow]; 
ENDCASE; 
ENDCASE ; - WITH z: input 
ENDLOOP; 

}; 

— Establish a new translator for this window and save the old one 
Enter: PROC [window: Window. Handle] = { 

translator: TIP.CharTranslator ^ fproc: MyKeyToCharProc. data; NIL! : 

TIP.SetInputFocus[w: window, takeslnput: TRUE); 

oldTrans * TIP. SetCharTr ans 1 ator f 
table:TIPStar. GetTable[TIPStar. Placeholder. blackKeys] , new: translator] ; 

}; 

" restore old translator when mouse exits window 
Exit: PROC [window:Wi ndow. Handle] - { 
[] TIP. SetCharTrans 1 ator f 
table: TlPStar. SetTablelTIPStar. Placeholder. blackKeys] , new: oldTrans]; 

}; 
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Stuffing Input into a Window 

TIP provides procedures that drive the type-in mechanism as if the 
characters were coming from the user, it is possible to stuff single 
characters, XStrings, Mesa STRINGS, and the current selection. When these 
objects are stuffed, your TIP.NotifyProc is called with a result of type string. 

MyNotifyProc: TIP.NotifyProc = ( 
FOR input: TIP. Results ^ results, input. next UNTIL input « NIL DO 
WITH z: input SELECT FROM 
string => ( 

XString.AppenclReacler[to: @wb, from: @z.rb! XString. Insuff icientRoom => 
CXString.ExpandWriterlw: @wb, extra: 20]; RETRY}]; 
Window. InvalidateBox [window: window, box: ( [0,0] ,[1000,1000] ]] ; 
Window. Validate [window: window]}; 
atom a> SELECT z.a FROM 

enter Enter [ wi ndow ] ; 
exit -> Exit[windowl ; 
ENDCASE; 
ENDCASE ; - WITH z: input 
ENDLOOP; 

}; 

StuffChar: MenuData.MenuProc = [ 
body: Window. Handle StarWi ndowShe 11 .GetBody[ [window] ] ; 
[] ^ TIP . Stuff Char acter [ wi ndow; body, char: XCharSetO.Make[upperH] ] ; 
}; 

StuffSe lection: MenuData.MenuProc = { 
body: Window. Handle * StarWindowShell .GetBody[ [window] ] ; 
[] TIP . Stuf f CurrentSel ect i on [ wi ndow; body 1 : 

}; 

StuffString: MenuData.MenuProc = { 
body: Window. Handle * StarWindowShell .GetBodyf [window] ] ; 
rb: XString. ReaderBody ^ XString. FromSTRING[ "sample string"L]; 
[] TIP. Stuff String [window: body, string: @rbj; 

}; 
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Selection 

The Selection interface defines the abstraction that is the user's "current 
selection." 

Selection provides procedures that allow someone (other than the 
originator of the selection) to request information relating to the selection 
and get this information in a particular format. 
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Selection 

There are two classes of clients who use the Selection interface. 

Requestors only want to obtain the value of the current selection in some 
format. 

Managers want to modify the current selection (i.e., change what it is that's 
selected) and thus require a thorough knowledge of Selection. 
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Selection 

The following chart shows some examples of selection situations, Who're 
the requestor and manager in each situation? 



Situation 


Requestor 


Manager 


User selects text in a document 






User drops a document (that was on 
the desktop) onto a file drawer 






Application takes the current icon 
selection & loads its contents into a 
window 
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Selection Example 

The goal of Selection is for the requestor to never care what program is 
managing the selection. All that matters is whether the selection can be put 
in a proper form or not. 




The user copies or moves an 
icon and drops it on a printer. 




The printer implementation only 
cares whether the selection can be 
converted to an Interpress Master. 
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Converting a Selection 

The most common operation performed by a selection requestor is to get 
the value of the current selection by calling Select ion. Convert: 

Select ion. Con vert: PROCEDURE[ 
target: Selection, Target, 
zone: UNCOUNTED ZONE ^ NIL] 
RETURNSC val ue : Sel ection . Val ue] ; 

Selection. Target: TYPE = MACHINE DEPENDENT { 

w1ndow(0), shel 1 . subwindow, string, length, position, 
integer, interpressMaster , file, fileType, token, help. 
interscriptScrlpt , InterscriptFragment , serial IzedFile, 
name, firstFree, 1 ast( 1777B)} ; 

Selection. Value: TYPE = RECORD[ 
value: LONG POINTER, 

ops: LONG POINTER TO Sel ection .Val ueProcs NIL. 
context: LONG UNSPECIFIED 0]; 

The Target is the TYPE of data the selection should be converted to. The 
Value is a RECORD containing a pointer to the converted selection. 
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Example Using Selection. Convert 

An important point to remember is that Convert returns a read-only value; 
you can only inspect it. Also, any storage associated with that value must be 
freed when you are finished. 



streamHandle: Stream. Handle GetStreamToSomeFilel ] ; 
xfo: XFormat, Object; 

xfo XFormat.StreamObjectl StreamHandle] ; 

— NIL Is returned if the selection cannot be converted 

savedString: Selection. Value Selection. Convert f string) : 

IF savedString. value - NIL THEN ( 

Stream. Delete I StreamHandle I ; 

RETURN}; 

XFormat. Reader I @xfo, LOOPHOLE [savedString. value] ] ; 
stream. Delete [streamHandle] ; 
Sel ect ion. Free f@savedStri nq ] ; 
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Freeing a Selection 

As you saw on the previous page, the requestor is responsible for freeing 
the temporary storage allocated in the manager's domain by calling 
Selection. Free. This call invokes a manager-supplied call-back procedure 
to free the storage. This call-back procedure may be a no-op procedure if no 
temporary resources were allocated when converting the selection. 

Selection. Free: PROCEDURE[v: Sel ection . Val ueHandl e] ; 
Selection. ValueHandle: TYPE = LONG POINTER TO Selection. Value; 
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Converting a Selection to a New Target 

The requestor can create a new Target by using Selection. UniqueTarget. 
The type associated with each Target is determined by system-wide 
convention. 

Select Ion. UniqueTarget: PROCEDURE RETURNS[Se1 ect1 on. Target ] ; 

This procedure returns a Target within the range of Selection .Target. You 
should use private target types judiciously since they severely limit the 
exchange of information between applications. 

my Target: Select ion. Target Select lon.UniqueTarqet f ] ; 

It's important to remember that a new target is useless without a selection 
manager to implement the target. 
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Can You Convert the Selection 

Not all selections will convert to all target types; thus, you may want to ask 
if a given selection will convert. To do this, you should call 
Selection, CanYouConvert, which returns a BOOLEAN specifying whether the 
value will convert to the particular target type. 

— this type of procedure is generally called from the canYouTakeSelection arm 
of a Containee.GenericProc 

CanlTake: PROCEDURE RETURNS (yes: BOOLEAN 1 = C 
— take anything that is a string, token, or integer 
RETURN ( 

Se 1 ect i on . Can YouConvert f target ; string, enumeration: FALSE] OR 
Se 1 ect 1 on . CanYouConvert ( target : i nteger , enumerat i on : FALSE ] OR 
Selection-CanYouConvertltarget: token, enumeration: FALSE]]; 

}; 

To determine the difficulty that the manager would have in attempting to 
convert to the specified target, you can call Sel action. HowHard. 

Selection. HowHard: PROCEDURE[ 
target: Selection. Target, 
enumeration: BOOLEAN ^ FALSE] 
RETURNS[diff iculty: Selection .Difficulty] ; 

Selection. Difficulty: TYPE = { 

easy, moderate, hard, impossible}; 
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Enumerating Selections 

A selection is often a collection of items (several files in a folder) or a single 
large item that can be split up (e.g, a LONG STRING that can be broken up). 
A requestor can ask that each item or part of such a selection be converted 
to some Target by calling Selection. Enumerate. 

~ called from GenericProc when selection Copyed or Moved to icon. 
" This proc appends the current selection to the end of a file 
Absorb: PROCEDURE [data: Containee.DataHandle] = [ 

AbsorbStrIng: Sel action. EnumerationProc =» C 

< < lelemenf.Selection.Value, data: Selection.RequestorData]> > 

XFormat. Reader [@xfo, LOOPHOLE I el ement. val ue ] ] ; 

Se 1 ect ion. Free { @e 1 ement I ; 

}; 

xfo: XFormat. Object; 

fileStream: NSF 11 eStream. Handle ^ GetStream [data]; 
stream . SetPos i t i on [ f i 1 eStream , NSFi 1 eStream .GetLength [ f i 1 eS tream 1 ] ; 
xfo ^ XFormat. StreamObject (f ileStreaml ; 
SELECT TRUE FROM 
Se 1 ect i on. CanYouConvert[ target: string, enumeration: FALSE] => 

[ 1 AbsorfaStrinqf Select ion. Convert [string ] . NIL] ; 
Selection. CanYouConvert[target: string, enumeration: TRUE] => 
[ ] Selection. EnumeratefAbsorbStrinq, string. NIL]: 
ENDCASE; 

S tream . De 1 ete [ f i 1 eStream j ; 

}; 
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Copying and Moving the Value of the Selection 

Convert and Enumerate return read-only Values. The selection manager 
owns the storage. The requestor must not alter the value. 

If the requestor wants to keep the value or pass the value to another 
process, it must call Copy, Move, or CopyMove. These three procedures call a 
manager-supplied procedure that allows the requestor to alter the value of 
the selection without affecting the selection manager. 

If Move is called, the value is also deleted from the manager's storage 
domain. After a Move or Copy, the requestor owns the Value. The requestor 
should eventually Free the storage. 

Selection. Copy: PROCEDURE[ 

v: Selection. ValueHandle, data: LONG POINTER] » INLINE { 
Selection .CopyMove[v , copy, data]}; 

Selection. Move: PROCEDURE[ 

v: Selection. ValueHandle. data: LONG POINTER] = INLINE { 
Selection. CopyMove[v. move, data]}; 

Sel ection . CopyMove : Sel ection . Val ueCopyMoveProc ; 

Selection. ValueCopyMoveProc: TYPE = PROCEDURE[ 

v: Selection. ValueHandle, op: Selection. CopyOrMove, 
data: LONG POINTER]; 

Sel ection. CopyOrMove: TYPE = {copy, move}; 
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Copying and Moving the Value of the Selection (cont'd) 

After calling Copy, Move, or CopyMove, the requestor then owns v . val uet and 
can alter it. 

A requestor may call these procedures after calling Convert or from an 
EnumeratlonProc while doing an Enumerate, data is passed to the manager; 
what it points to depends on the particular Target, data often points to a 
destination container for the copied value. 
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Managing the Current Selection 

The fundamental operation performed by a selection manager is to become 
the current manager by calling Selection. Set, which takes a ConvertProc, 
an ActOnProc, and a long pointer (Manage rOata). 

Selection. Set: PROCEDURE[ 

pointer: Selection. ManagerOata. 
conversion : Selectlon.ConvertProc, 
actOn: Selection. ActOnProc]; 
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The ConvertProc 

ConveptProc is called to obtain the value of the selection whenever a 
requestor calls Selection. Convert or Selection. Enumerate. 

It's also called to determine what Targets the selection can be converted to 
whenever a requestor calls CanYouConvert, Query, or HowHard. 

Select ion. Set: PROCEDURE (pointer: Selection.ManagerOata, 
convers ion; Se 1 ect i on . ConvertProc . actOn: Selection.ActOnProc] ; 

Selection. Convert: PROCEDURE! 
target: Selection. Target, zone: UNCOUNTED ZONE * NIL] 
RETURNS[value: Selection. Value] ; 

Selection. ConvertProc: TYPE « PROCEDURE[ 
data: Selection.ManagerOata, - long pointer 
target: Select Ion. Target, '-type to convert selection to 

zone: UNCOUNTED ZONE, 

Info: Selection .Converslonlnfo [convert[ ]]] 
RETURNS[ val ue : Sel ectlon . Val ue] ; 

Selection. Value: TYPE = RECORD[ 
value: LONG POINTER, 

ops: LONG POINTER TO Sel ectlon .Val ueProcs ^ NIL, 
context: LONG UNSPECIFIED ^ 0]; 
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The ConvertProc "Conversionlnfo" 

Conversioninf o is a variant record passed to the ConvertProc that indicates 
which operation to perform: convert, enumeration, or query. 

Selection. Conversioninf o: TYPE = RECORD[ 
SELECT type: ♦ FROM 
convert »> NULL, 
enumeration [ 

proc: PR0C[Se1ect1on. Value] RETURNS[stop: BOOLEAN]], 
query => [ 

query: LONG DESCRIPTOR FOR ARRAY OF 
Select ion. Query Element] , 
ENDCASE]: 

Selection.QueryElement: TYPE = RECORD [ 
target: Select ion. Target, enumeration: BOOLEAN ^ FALSE, 
difficulty: Selection. Difficulty TRASH]; 
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The ConvertProc "value" 

When the requestor calls Selection. Convert, the manager's ConvertProc 
gets called with convert Conversioninf o. If the ConvertProc can convert 
data, the value. value returned should point to the converted selection 
value. Additionally,value.ops should point to a record containing a 
ValueFreeProc and a ValueCopyMoveProc, and value. context can be used as 
"client data." 

If the manager doesn't support conversion to the requested target, the 
ConvertProc should return null Value. 

Selection. ConvertProc: TYPE = PROCEDURE[ 
data: ManagerOata, target: Target, 
zone: UNCOUNTED ZONE, 
info: Conversioninf o [convert[ ]]] 
RETURNSC val ue : jVaTue]] ; 

-4rr- 

|.y_a_l_ue_c TYPE = RECORD[ 

value: LONG POINTER, ^ 

ops: LONG POINTER TO Ji/aXueProcs NIL, 
context: LONft^UHSPECfFiED ^ 0]; 

LYiLluefJ-OCSj _TYPE _=^ 

free:! ValueFreeProc!^ NIL, 

■< — .. I . — I— , 

copyMove,;r^aJueC_oq^Mo_veP_r^^ ^ NIL]; 
'y.^}}L^l£?A^£^^ = PROCEDURE[v: ValueHandle] ; 



1 ValueCopyMoveProd: TYPE = PROCEDUREf 

v: ValueHandle, op: ICopyOrMov^, data: LONG POINTER]; 



r 1 

L??PJ^Qr*l0Y?^ TYPE = {copy, move}; 
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Sample ConvertProc 

The following sample ConvertProc supports conversions of the current 
selection to the targets string, integer, and f ileType. Enumeration is not 
supported. 

MyConvertProc: Selection. ConvertProc = C 

< <[data: 5e/ection.ManagerOata, target: Selection.Target zone: UNCOUNTED ZONE, 
info: Se/ection.Conversionlnfo] RETURNS[value: Seiection.Valuel> > 

String: XString. Reader *■ NARROW(clata, XS tring. Reader ] ; 
WITH i: info SELECT FROM 

query => (FOR x: CARDINAL IN [0. .LENGTH! i .query] ) 00 
i .querylx] .difficulty * 
IF i. query (xj. enumeration THEN impossible 
ELSE SELECT i .query [x 1 .target FROM 
string => easy, 

integer, f ileType => moderate, 
ENDCASE => impossible; 

ENDLOOP; 
RETURN I Se 1 ect i on . nu 1 1 Va 1 ue ] } ; 
convert => SELECT target FROM 

str i ng < < do something here > > 
i nteger , f i 1 eType => << do something here > > 
ENDCASE => RETURN[Selection. null Value]; 
ENDCASE => RETURNlSelection.nul lvalue]; 

}; 
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TheActOnProc 

ActOnProc is called to perform various Actions on the selection, such as mark, 
unmarlc, and clear. 

Selection. Set: PROCEDURE [pointer: Selection.ManagerOata, 
conversion: Select ion. Convert Proc, actOn: Sel ect ion. ActOnProc 1 : 

Selection, ActOnProc: TYPE = PROCEDUREC 

data : Se 1 ect 1 on . Manage rOata , - long pointer (usually points to a record) 
action: Selection. Action] — Perform some action on current selection 
RETURNS[cl eared : BOOLEAN] ; - should be TRUE if selection was cleared 
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Actions the ActOnProc Can Perform 

Selection. Action: TYPE = MACHINE DEPENDENT { 

clear(O), marlc, unmarlc. delete, clearlfHasInsert, save, 
restore, firstFree, last(Z56)}; 

clear unselects the current selection by freeing any associated 

private data, undoing TIP notification changes, etc. 

mark highlights the current selection; if the selection is 

already highlighted, this is a no-op. 

unmark dehighlights the current selection; if the selection is 

already not highlighted, this is a no-op. 

delete deletes the contents of the current selection. The 

selection manager may decide against actually deleting 
it. 

clearlfHasInsert same as unmark plus clear, but only if the input focus is ^ 

in the selection. This action is used when a secondary 
selection has been completed (for copy-from); if the 
place to which the secondary selection is to be copied 
(the input focus) is within the selection itself, the 
selection is cleared after obtaining its contents and 
before the insertion takes place. 

save unselects the current selection, but does not necessarily 

free any associated private data since the selection is 
expected to be restored later. This action will often be a 
no-op, but the manager might need to undo a special 
TIP notifier, for example. 

restore restores a previously saved selection. 

firstFree is used internally by UniqueAction and should not be 

used by clients. 
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Sample ActOnProc 

The following sample ActOnProc shows a basic format for handling actions: 



MyActOnProc: Selection. ActOnProc - { 

< <[data: Selection.ManagerOata, actiontSelection.Action] RETURNSldeared: BOOLEAN] > > 

String: XString. Reader NARROW[data, XStr ing. Reader ] ; 
SELECT action FROM 

mark => < < highUght current selection &lor set data > > ; 

unmark s> < < dehighlight current selection Alorset data > > ; 

clear cleared * TRUE; 

save -> NULL; 

ENDCASE => {mh: XMessage. Handle Def s.GetMessageHandle{ ] ; 
msg: XString. ReaderBody 

XMessage.Get[mh, Defs.kunknownAction] ; 
Attent i on . Post I @msg ] } ; 

}; 
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The ManagerData 

The ManagerData passed to Set is passed back to the ConvertProc and the 
ActOnProc. Typically, ManagerData identifies exactly what portion of the 
manager's domain is currently selected. For example, if the current selection 
is some text in a document, the actual manager is the document application, 
which has some ManagerData that indicates exactly which characters are 
currently selected. 

When a manager calls Select ion. Set, the previous manager is told to 
ActOn[clear] and Selection forgets about the previous manager. Hence, 
there is only one selection at a time. 
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Other Selection Procedures 

Selection. Clear: PROCEDURE[unmarlc: BOOLEAN TRUE]; 

Clear clears the current selection. The only time unmaric should be FALSE is if 
the caller knows that the area of the screen containing the selection is going 
to be repainted soon anyway. 

Clear[unmarlc: TRUE] is equivalent to 
{ ActOn[unroaric]; ActOn[clear] }; 

Selection.ActOn: PR0CEDURE[act1on: Selection. Action]; 

ActOn asks the manager to perform the indicated action. 
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ValueProcs 

What happens when a requestor calls Selection. Copy or Selection. Free? 
It's highly dependent on what the selection is and the type to which that 
selection was converted. So that the requestor doesn't have to worry about 
these details, the selection manager provides ValueProcs. 

The Value produced by a manager's ConvertProc contains a pointer to two 
procedures, a ValueFreeProc and a ValueCopyMoveProc. The Val ueFreeProc 
is called when a requestor calls Selection. Free so that the manager can 
release any resources that were allocated when the selection was converted. 
The manager's ValueCopyMoveProc is called when the requestor calls Copy, 
Move, or CopyMove. The ValueCopyMoveProc should copy or move the 
converted selection value so that the manager no longer owns the resources 
associated with the value, context may be used to store data for the 
ValueFreeProc and the ValueCopyMoveProc. 
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ValueProcs (cont'd) 

If the converted selection value can be copied or moved, the manager must 
return a ValueCopyHoveProc with the Value. For example, the Targets 
string and file can be moved or copied, while it doesn't make sense to 
move or copy the Targets window and fileType. The ValueCopyHoveProc 
modifies the Value such that the requestor may then make changes to 
val uet without affecting the selection manager. If a Move is performed, the 
item is also deleted from the manager's domain. The interpretation of the 
data given to a ValueCopyHoveProc depends on the manager; a typical use is 
to specify a destination for the object. 

Selection. ValueHandle: TYPE » LONG POINTER TO Selection. Value; 

Selection. Value: TYPE = RECORD[ 

value: LONG POINTER, - pointer to the current selection 

ops: LONG POINTER TO Sel ection . Val ueProcs ^ NIL. 
context: LONG UNSPECIFIED ^ 0]; 
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ValueFreeProc 

Selection. ValueFreeProc: TYPE = PROCEDURE[ 
v: Selection. ValueHandle]; 

If any resources were allocated to produce the converted selection value, 
they should be released in the manager's ValueFreeProc when the 
requestor calls Selection. Free. The parameter v is a long pointer to the 
Value that represents the converted selection. 

Sel ection . FreeStd : Sel ection . Val ueFreeProc ; 

This procedure assumes that v. context is a zone and that v. value can be 
freed by calling v. context. FREE[@v. value]. Free calls FreeStd when the 
Value has ops » NiLor ops. free = NIL. 

Sel ection .Nop Free: Selection .Val ueFreeProc; 

This procedure should be used as the ops. free for a Value involving no 
temporary storage owned by the selection manager. 
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ValueCopyMoveProc 

Selection. ValueCopyMoveProc: TYPE = PROCEDURE[ 
v: Selection. Va1ueHand1e. 
op: Selection. CopyOrMove, 
data: LONG POINTER]; 

Selection. CopyOrMove: TYPE = {copy, move}; 

The procedures Copy, Move, and CopyMove invoke the Value's 
Val ueCopyMovePpoc, which should modify Val ue so that it no longer involves 
manager-owned storage. If the requestor calls Move, then the item is also 
deleted from the manager's domain, data is the data parameter that the 
requestor passed to Copy, Move, or CopyMove, and is often a container for the 
copied value. 

For managers that want to support Copy but not Move (i.e., the manager 
refuses to delete the selection), an attempt to Move should raise 
Selection. Error[ in val idOperation]. 

If the operation is permitted but nevertheless fails (e.g., due to an NSFile 
error). Selection. Error[operationFailed] should be raised. 
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Save and Set 

Selection supports the notion of a "saved selection." A client can become 
the current manager by calling Selection. SaveAndSet, which does a Set but 
also saves the previous selection. Later, the manager that did the 
SaveAndSet can do a Selection. Restore to restore the previous selection. 

Se 1 ect Ion . SaveAndSet : PROCEDURE[ 
pointer: Sel ect Ion. Manage rOata, 
conversion: Selection .ConvertP roc , 
actOn: Selection .ActOnProc, unmaric: BOOLEAN ^ TRUE] 
RETURNS[old: Selection. Saved]; 

Selection. Saved: TYPE [6]; 

Selection. Restore: PROCEDURE[ 

saved: Selection .Saved , marie, unmaric: BOOLEAN *- TRUE]; 

Selection. Discard: PR0CEDURE[ 

saved: Selection .Saved , unmaric: BOOLEAN <- TRUE]; 

SaveAndSet is the same as Set except that the existing selection, if there is 
one, is told to ActOn[save] rather than ActOn[clear]. That is, the existing 
selection is expected to retain any private state so that it can later be 
restored via Selection. Restore. If it subsequently turns out that the saved 
selection is never going to be restored, it should be given to 
Selection. Discard so that the former selection manager will have a chance 
to discard any associated private data. A saved selection must always be 
eventually given to either Restore or Discard; furthermore, once that has 
been done, the Sel ect ion. Saved must not be used for anything else. 
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Selection Example 

The following code implements the selection of a unique target ("boxes"). 




Boxes tool and icon 



BoxesOefs: DEFINITIONS = { 
2: UNCOUNTED ZONE; 

Shading: TYPE « {white, gray, black}; 

SelectionPtr: TYPE = LONG POINTER TO SelectionOata; 

SelectlonOata: TYPE = RECORD [ 
w i ndow : W i ndow . Hand 1 e , window containing the box 
place: Window. PI ace [0, 0], - window relative box pos 
dims: Window. Dims [40, 40], -boxdims 
shading: Shading *- white, — changed via props command 

marked: BOOLEAN FALSE, - used by ActOnProc 

zone: UNCOUNTED ZONE NIL]; - zone where rec is allocated 

Data: TYPE = LONG POINTER TO DataObject; 

DataObject: TYPE = RECORD [ 

cou nt : CARD I NAL 0 , - currently in use (seq is kept compressed) 
boxes: SEQUENCE max length: CARDINAL OF SelectionPtr]; 



... 



Day 2: Selection 



Advanced Viewpoint Programming Class - January, 1968 



2-31 



Boxes Impl: PROGRAM - ( 
" We create our own target type 

box; PUBLIC Select ion. Target = Selection.UniqueTarqetf 1 : 

ODsProcs; Selection. ValueProcs 

[free: Selection.NopFree, copyMove: CopyMoveBox 1 ; 

MyNotifyProc: TIP.NotifyProc » C 

<< [window: Window.Handle, results: Results] >> 

boxNum: CARDINAL; 

place: Window. PI ace; 

data: Defs.Data GetContext [window]; 

FOR input: TIP. Results _ results, input. next UNTIL input = NIL 00 
WITH z: input SELECT FROM 
coords *> place +• z. pi ace; 
atom SELECT z.a FROM 

pointDown => { select or deselect a box 
TIP.SetInputFocus[w: window, takes Input: FALSE]; 
boxNum 0efs.0ver6ox[ window, data, place]; - are we over a box? 
IF boxNum # LAST [CARDINAL] THEN - over some box so select it 

Def s.SelectBoxiwindow, data, place, boxNum] 
E LSE Se 1 ect i on . C 1 ear [ ] } ; - not over a box so deselect current box 
copyDown «> Def s . CopyBox [ wi ndow , data , p 1 ace ] ; 
moveOown -> Def s. Mo veBox[ window, data, pi ace ] ; 
copy Def s. Copy [wi ndow 1 ; 

move => Def s. Move [wi ndow j ; 
delete => Def s. Delete [window ] ; 
ENDCASE; 
ENDCASE; - WITH z: input 
ENDLOOP; 



" This proc establishes a new current selection. The call to Set will unmark and clear the old 
— selection. Set then automatically calls the ActOnProc with mark for the new selection. 
SelectBox: PUBLIC PROC[ 
wh: Window. Handle, data: Defs.Data, place: Window. Place, 
boxNum: CARDINAL] = { 
Selection. Set f 
pointer: data[boxNum] , 
conversion: ConvertSelection, 
actOn : ActOnSe 1 ect ion]; 
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" mark or unmark the current selection. If the client wants to delete the selection then delete is 
- invoked, which deletes the box from the manager's domain and clears the selection manager. 
ActOnSelection: Selection.ActOnProc = ( 

<<[data: Selection. ManagerOata, action: Selection.Action] 

RETURNSfcieared: BOOLEAN ^ FALSE] > > 

selectionOata: Defs.SelectionPtr *■ NARROW[data, Defs.SelectionPtr] ; 
SELECT action FROM 
mark «> IF 'selectionOata. marked THEN 

ClnvertBox(selectionOata] ; selectionOata. marked TRUE}; 
unmark => IF selectionOata. marked THEN 

{InvertBoxI selectionOata] ; selectionOata. marked ^ FALSE}; 
delete => IF selectionOata. marked THEN 

{InvertBox{ selectionOata] ; selectionOata. marked FALSE; 
DeleteBox[ selectionOata] ; 
RETURN(TRUE]}; 
clear => RETURN { TRUE ] ; 
ENOCASE «> { 
mh: XMessage. Handle - Oefs.GetMessageHandle[ ] ; 
msg: XString.ReaderBody XMessage. Get [mh, Def s.kunknownAction] ; 
Attent i on . Post [ @msg 1 } ; 

}; 

InvertBox: PROCl selectionOata: Defs.SelectionPtr] - { 
Oisplay. Invert! 
window: selectionOata. window, 
box: [select ionOata.pl ace, 

[selectionOata. dims. w + 1, selectionOata. dims. h + 1]]]; 

}; 

ConvertSe lection: Selection.ConvertProc =» [ 

<<[data: Selection. ManagerOata, target: TARGET, zone: UNCOUNTED ZONE, 
info: Selection.Conversionlnfo] RETURNS [value: Selection. Value] > > 
selectionOata: Defs.SelectionPtr NARROW[data, Defs.SelectionPtr]; 
WITH i: info SELECT FROM 

query »> FOR c: CARDINAL IN [ 0. . LENGTH [ i , query ]) DO A©«sw^^ 
1.query(c] .difficulty IF (i «query[c] .target = box) OR ^Ji<w^"^'^ 

(i .query! c] .target = window) THEN easy 
ELSE Impossible A 

ENDLOOP: 

convert => { r^p.c>^ 
SELECT target FROM 
window «> RETURN! [ 

selectionOata.window,Selection.nopFreeValueProcs] ] ; 
box s> 

RETURN! [value: selectionOata, 

ops: @opsProcs, -nop free proc 
context: LOOPHOLE [zone]] ]; 
ENOCASE «> RETURN(Selection.nul lvalue]}; 
enumeration RETURN [Selecti on. nu 11 Val ue ] ; 
ENOCASE; 
RETURN ! Se 1 ect i on . nu 1 1 Va 1 ue 1 ; 

}; 
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" If there is a current selection then set cursor to copy; othePAfise post a message to the user 
Copy: PROClwindow: Window. Handle] = { 
val; Selection. Value Se lect ion. Convert [ box ] ; 
IF val. value = NIL THEN { 
mh: XMessage. Handle = Defs.GetMessageHandlel ] ; 
msg: XString.ReaderBody XMessage. Get [mh, Defs.kunknownActionl ; 
Att ent i on . Post I @nisg 1 ; 
RETURN}; 

Selection. Freef@val I ; - should always call even if it's a nop 
Cursor . Set [ copy 1 ; - set cursor to copy mode 
(1 TIPStar.SetMode(mode: copy); 

}; 

— called if in copy mode and user performs a point down 
a copy of the box is made and placed at "place" 

CopyBox: PROC[ 

window: Window. Handle, data:Oef s.Data, place: Window. Place] = { 
value; Selection. Value Select ion. Con vert [target; box] ; 
boxPtr: Oef s.SelectionPtr; 
IF value. value = NIL THEN { 

mh: XMessage. Handle - Defs.GetMessageHandle[ ] ; 

msg: XString.ReaderBody XMessage. Get [mh, Oefs.kunknownAction] ; 

Attention.Post[@msgl ; 

RETURN); 

Selection. Copy[v: lvalue, data: data! ; - make copy store in value, value 

boxPtr NARROW[value. value, Def s.SelectionPtr] ; - loophole to maice usable 

AddToManager[ window, data, boxPtr, place, lvalue]; -add to manager's domain 

Selection. Free[@value] ; 

Cursor.Set[textPointer] ; 

[] TIPStar.SetMode[mode; normal]; 

}; 

— when the user copies or moves an object to a new location, 

— it must be added to the manager's data. 
AddToManager: PROC[ 

window: Window. Handle, data: Defs.Data, boxPtr: Oefs.SelectionPtr, 
place: Window. Place, v; Selection. ValueHandle] * C 
data[data. count] boxPtr; 

data[data. count] .window window; -the box belongs to the dest window 
boxPtr . p 1 ace p 1 ace ; — give copied box a new location 
SelectBox[ window, data, place, data. count]; -set the new current selection 
data. count * data. count + 1; 
Window. Inval idateBox[ 
window: window, 

box: [boxPtr.pl ace, boxPtr.dimsJ] ; 
Window. Validate [window] ; 
}; 
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make copy of the current selection and store it in v. value. If the call was a copy then simply return. 
If the call was a move then delete the information from the manager's domain storage is used 
CopyMoveBox: Selection.ValueCopyMoveProc - { 

< </v: Selection.ValueHandle, op: SelectionXopyOrMove, data: LONG POINTER] >> 

z: UNCOUNTED ZONE * LOOPHOLE (v. context 1 : 

old: DefSoSelectionPtr v. value; - keep pointer to manager's object 
" allocate another box element that will be returned to caller 
new: Defs.SelectlonPtr ■*■ v. value z.NEW[Defs-SelectionData old+]; 
new .zone ^ z; —save the zone that we allocated from 

IF op = move THEN { 
Selection. Clearfunmark: FALSE]: - remove the selection manager 
De 1 eteBox [old]; — delete the object from the manager's domain 

}; 

}; 

~ Delete the box from the manager's domain and redisplay the window. 
DeleteBox: PROClbox: Def s.SelectionPtr] = ( 

window: Window. Handle * box. window; 

mydata: Def s. Data Defs.GetContextlwindow] ; 

1: CARDINAL; 

W i ndow • I nva 1 1 dateBox [ - this area will need repainting after deletion 
window: window, 
box: [box. place, box.dims]]; 
FOR i IN [0.. mydata. count) 00 - first find the element and delete it 
IF mydata! i] = box THEN { 
mydata! i 1 .zone.FREEl@niydatali 1 ] ; 
EXIT}; 
ENDLOOP; 

FOR i IN [i. .my data, count -1) 00 - compact data structure 
mydata.boxesli 1 mydata.boxes( i +1]; 
ENDLOOP; 

mydata. count ^ mydata. count - 1; 
Window. Validate[wi ndow] ; 

}; 
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Move: PUBLIC PR0C(w1ndow: Window. Handle] « C 
val; Selection, Value Se lection. Convert f box! ; 
IF val. value » NIL THEN { 

mh: XMes sage. Handle - Oefs.GetMessageHandle[ ] ; 

msg: XString.ReaderBody ^ XMessage.Get [rah, Defs.kunknownActionl ; 

Attention. Post (@nisg] ; 

RETURN}; 
Selection. Freef@val 1 ; 
Cursor. Set(movel ; 
(1 TIPS tar. SetMode( mode: move]; 
}; 

— When the user does a pointDown while moving a box we must add 
" the box to the manager's data, thus giving the manager control. 
MoveBox: PUBLIC PROCl 

window: Window. Handle, data:Defs.Data, place: Window, Place] -[ 

boxPtr: Defs.SelectionPtr; 

val: Selection. Value Selection. Convertf box] ; 

IF val. value = NIL THEN { 

mh: XMessage. Handle - Oefs.GetMessageHandlef ] ; 

msg: XString.ReaderBody * XMessage.Get (mh, Defs.kunknownAction] ; 

Attent i on . Post I @msg ] ; 

RETURN}; 
Selection.Movef^val . NIL] : 
boxPtr * NARROW I val. value, Defs.SelectionPtr]; 

AddToManager (window, data, boxPtr, place, @val]; - add to manager's domain 

Selection. Freef@val ] ; 

Cursor . Set ( textPo i nter ] ; 

(1 * TIPStar.SetModelmode: normal]; 

}; 

— delete the box from t/ie manager's domain 

Delete: PUBLIC PROC(window: Window.Handle] » { 
Selection. ActOnf delete] : 
}; 

}... 
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Doclnterchange 

DocInterchangeDef s provides client programs with the ability to create or 
enumerate Viewpoint documents. Document structures such as text, fields, 
headings/ footings, and tiles (paragraph, page breaks, etc.) are supported. 
DocInterchangeDefs does not support creation or enumeration of frame 
content (e.g. tables, graphics); these objects are supported by their own 
interfaces. 

We will also discuss the DocInterchangePropsDef s interface, which defines: 

Page Properties 
Field Properties 
Font Properties 
Paragraph Properties 
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Doclnterchange 

This slide shows some of the objects that an application can append to a 
document with DoclnterchangeDefs. In addition, you can manipulate the 
objects' properties using additional interfaces. 



Paragraphs 



Headings 




1^. 



Page format 
characters 
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towards, the . opponent's .side. of .the. board.. A.player. wins. when. he's.jumped. all. of. the. opponen 
pieces,,; 

i^Ty£j e i^.ca n .co n ta i n .te x t.o r 

but.not.another.fieldJvl 




Frames 



Fields 



Page brealcs 



Text 
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w Document Creation 

The three steps in document creation are: starting creation, appending 
objects to the document, and finishing creation. In order to start creating a 
document, you call DocInterchangeDefs.StartCreatlon. NIL values in the 
call to StartCreatlon cause the defaults to be used for the specified 
properties. 

In examples, you will see the abbreviation Dl and DIP used in place of 
DoclnterchangeDefs and DoclnterchangePropsDefs respectively. 

DI. StartCreatlon: PROC[ 

paglnateOption : DI . PaglnateOption compress, 
wantHeadingHandles , wantFootingHandles : BOOL ^ FALSE, 
Initial FontProps: DIP. ReadonlyFontProps NIL, 
initial ParaProps : DIP. ReadonlyParaProps NIL. 
initialPageProps: DIP. ReadonlyPageProps ^ NIL] 
RETURNS[ 
'^m^ doc: DI.Doc, 

leftHeading, rightHeading : DI. Heading, 

leftFooting, rightFooting : DI. Footing, 

status: Dl.StartCreationStatus]: 

DI.Doc: TYPE = LONG POINTER TO DI.DocObject; 
DI.DocObject: TYPE; 

D I. PaglnateOption: TYPE = { 
none, simple, compress, firstAvallable, lastAvail able (255)}; 

Dl.StartCreationStatus: TYPE = MACHINE DEPENDENT { 
ok(0), notEnoughDiskSpace, notEnoughVM, firstAvallable, lastAvail able (255)}; 
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Document Creation (cont'd) 

While StartCreation looks complicated, all arguments to the procedure can 
be defaulted and the only essential return argument is doc. doc can be 
thought of as a handle to the unfinished document that is used when 
appending objects to that document. We will discuss the xxxProps 
arguments in detail later. 

You can request that StartCreation return headings and footings for the 
new document; these can then be set using the append routines. 

The paglnateOptlon should be set to either simple or compress (if the 
document will be more than a few pages long); otherwise, the user will 
experience poor editing performance, simple pagination gives the outward 
signs of pagination but the document is not in optimized form, compress 
paginates the document and places it in optimized form. 
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Appending Objects 

Once you have created a doc, you can begin appending objects to it (e.g. 
text characters). You append these objects to a 
DocInterchangeDefs.TextContalner, which is a variant record containing 
any of the different text-accepting areas of a document. Thus, if you opt for 
having headings or footings returned during StartCreation, you can 
append text to them using the same procedures as you would to append 
text to the body of a document. 

DI.TextContainer: TYPE = RECORD[ 
var: SELECT type: ♦ FROM 
caption => [h: DI. Caption], 
doc => [h: DI.Doc], 
field => [h: DI. Field], 
heading => [h: DI. Heading], 
footing => [h: DI. Footing], 

sparel => [h: DI.SpareTC], spares are for future compatability 
spareZ => [h: DI.SpareTC], 
spares => [h: DI.SpareTC], 
spare4 => [h: DI.SpareTC], 
ENDCASE]; 

DI.SpareTC: TYPE = LONG UNSPECIFIED; 
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Appending Characters 

To append a character, you call DocInterchangeDef s . AppendCha 

DI.AppendChar: PROC[ 
to: DI cTextContainer, 
char: XChar. Character, 
fontProps: DIP. ReadonlyProps «- NIL, 
nToAppend: CARDINAL 1]; 



Day 3: Doclnterchange and You 



Advanced Viewpoint Programming Class - July, 1988 



3-9 



w Appending XStrings 

You can append XStrlng . Readers to a text container by calling 
DocInterchangeOef s.AppendText. For efficiency, you should specify the 
appropriate context if it is known; otherwise, specify 
XStrlng. unknownContext. 

DI.AppendText: PROC[ 
to: DI .TextContalner, 
text: XStrlng .Reader, 
textEndContext : XSt ring .Context, 
fontProps: DIP. ReadonlyProps NIL]; 
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Appending Fields 

Appending fields to a TextContalner is as simple as appending characters; 
however, the field itself may contain additional objects. Notice that the call 
to DocInterchangeDefs.AppendFleld will not only append a field to some 
TextContalner, but it will also return the field to the client. The client can 
then append items to the field (except another field). 

When you finished appending information, the field must be released. 

DI.AppendFleld: PROC[ 
to: DI. TextContalner, 
fieldProps: DIP. ReadonlyProps , 
fontProps: DIP. ReadonlyProps <- NIL] 
RETURNS[f leld: DI. Field]; 

DI. Field: TYPE = LONG POINTER TO DI.FIeldObject; 
DI.FIeldObject: TYPE; 

DI.ReleaseFleld: PROC[f leldPtr: LONG POINTER TO DI. Field]; 
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Viewpoint Field Properties 



Field Properties 



Display 



FIELD 




SUMMARY 
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Type 



Format 
Range 
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Skip If field 
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EMPTY 
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Field Properties 

DIP.FieldProps: TYPE = LONG POINTER TO Fiel dPropsRecord ; 
DIP.ReadonlyPieldProps: TYPE - LONG POINTER TO READONLY DIP.FIeldPropsRecord; 

DIP.FieldPropsRecord: TYPE = RECORD[ 
language: Mul tINatlonal .Language, 
length: CARDINAL, 
required: BOOL, 
skiplf: DIP.SkipIfChoiceType. 
stopOnSklp: BOOL, 
type: DIP. FieldChoiceType, 

fllllnRule, " changing filUnRule implies changing filllnRuleRuns 

description, 

format, 

name , 

range, 

sklplf Flel d : XStrIng . ReaderBody , 
filllnRuleRuns: DIP. FontRuns , 
sparel: LONG CARDINAL]; 

DIP. FieldChoiceType: TYPE = MACHINE DEPENDENT { 
any(O), text, amount, date, firstAvailable, lastAvai1ab1e(255)}; 

DIP.SkipIfChoiceType: TYPE = MACHINE DEPENDENT { 
empty{0), notEmpty, never, always, firstAvailable, lastAvail able (255)}; 
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Appending Paragraphs 

You can append a paragraph character (with 
DocInterchangeDefs.AppendNewParagraph) to a text container and specify 
initial properties for the paragraph. You can then change the paragraph 
properties later (i.e. in the middle of a paragraph) with 
DocInterchangeDef s.SetCurrentParagraphProps. 

DI .AppendNewParagraph: PROC[ 
to: DI .TextContalner, 
paraProps: DIP. ReadonlyProps NIL, 
fontProps: DIP. ReadonlyProps NIL, 
nToAppend: CARDINAL <- 1]; 

DI . SetCu r rentParag raphProps : PROC[ 
textContainer: DI .TextContalner, 
paraProps : DIP . ReadonlyParaProps] ; 




Day 3: Doclnterchange and You 



Advanced Viewpoint Programming Class - July, 1988 



3-14 



Specifying Paragraph Properties 

Paragraph properties are divided into two classes: basic properties and tab 
stops. 
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Specifying Paragraph Properties (cont'd) 

You can specify paragraph properties via the DoclnterchagePropsDef s 
interface; if you default the paraProps argument, the new paragraph 
character will inherit the properties of the previous paragraph. 

DIP. ParaProps: TYPE = LONG POINTER TO DIP. ParaPropsRecord ; 
DIP.ReadonlyParaProps: TYPE = LONG POINTER TO READONLY DIP. ParaPropsRecord; 

DIP. ParaPropsRecord: TYPE = RECORD[ 
basicProps: DIP.BasicPropsRecord, 
tabStops: DIP.TabStops , 

spa re 1: LONG CARDINAL]; - spare is for future expansion 

DIP. BasicProps: TYPE = LONG POINTER TO DIP.BasicPropsRecord; 

DIP.ReadonlyBaslcProps: TYPE = LONG POINTER TO READONLY DIP.BasicPropsRecord; 

DIP.BasicPropsRecord: TYPE =» RECORD[ 
preLeading, postLeading, 

leftlndent, rightlndent, lineHeight: CARDINAL, 

paraAl ignment: DIP.ParaAl ignment, 

justified, hyphenated, keepWithNextPara: BOOL, 

language: Mul tiNational .Language, 

streakSuccession : DIP.StreakSuccession , 

def aul tTabStopSpacing : DIP.Def aul tTabStopSpacing , 

def aul tTabStopAl ignment: DIP.TabStopAl ignment, 

sparel: LONG CARDINAL]; 

DIP.ParaAl Ignment: TYPE = MACHINE DEPENDENT f 
left(O), center, right, f irstAvailable, 1astAvai1able(255)); 

DIP.StreakSuccession: TYPE « MACHINE DEPENDENT { 
leftToRight(O), rightToLeft. f irstAvailable, lastAva1lable(255)]; 
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Specifying Tab Properties 

Up to 100 tab stops may be associated with each paragraph object. 
DIP.nTabsMax: CARDINAL = 100; 

DIP.TabStops: TYPE = LONG DESCRIPTOR FOR ARRAY OF DIP.TabStop; 

DIP.TabStop: TYPE = RECORD[ 
dotLeader: BOOLEAN, 
tabStopOf f set : DIP . TabStopOf f set , 
tabStopAl Ignment : DIP.TabStopAl Ignment, 
sparel: LONG CARDINAL]; 

DIP.TabStopAl ignment: TYPE = MACHINE DEPENDENT { 
left(O), center, right, decimal, firstAvai Table, lastAvailable(255)}; 

D I P. TabStopOf f set: TYPE « CARDINAL; 

DIP.DefaultTabStopSpacing: TYPE = CARDINAL; 
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Appending Page Breaks 

Page breaks can only be appended to a DocInterchangeDef s.Doc; they have 
font properties that can either be client specified or defaulted. 

DI.AppendPageBreak: PROC[ 

to: DI.Doc. fontProps: DIP. ReadonlyProps ^ NIL]; 
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Specifying Font Properties 

Numerous fonts and sizes may be specified; however, the font that you 
choose must be on the local machine. 
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Specifying Font Properties (cont'd) 

If you default fontProps, then the font properties are inherited from the 
previous objects appended. You should note that all features of each font 
may not be implemented (e.g. modern is not fixed pitch). Font properties 
should be set only if they are known fonts; otherwise, you might create 
black boxes instead of characters. 

DIP. FontProps: TYPE = LONG POINTER TO DIP . FontPropsRecord ; 
DIP.ReadonlyFontProps: TYPE - LONG POINTER TO READONLY DIP. FontPropsRecord; 

DIP. FontPropsRecord: TYPE = RECORD[ 
fontDesc: DIP. FontDescrlption , 
offset: INTEGER, 

foregroundBackg round: DIP. ForegroundBackg round, 

nUnderllnes: CARDINAL, 

strikeout: BOOL, 

placement: DIP. Placement, 

toBeDeleted, revised: BOOL, 

width: DIP. Width, 

sparel: LONG CARDINAL]; 

DIP. FontDescrlption: TYPE = RECORD! 
family: DIP. Family, 
des i gnVar i ant : DIP. Des 1 gnVar 1 ant , 
posture: DIP. Posture, 
weight: DIP. Weight, 
pointSize: CARDINAL, 
serlfness: DIP.Serifness, 
sparel: LONG CARDINAL]; 



Day 3: Doclnterchange and You 



Advanced Viewpoint Programming Class - July, 1988 



3-20 



Specifying Font Properties (cont'd) 

DIP.DeslgnVariant: TYPE = MACHINE DEPENDENT { 
nun(O), roman, italic, firstAvai Table, lastAvailable(255)]; 

DIP. Family: TYPE = MACHINE DEPENDENT { 
century(O), frutiger(l), t1tan(2), pica(3), trojan(4), ... firstUnused(48), 
lastUnused(510), backstop(511)}; 

DIP.ForegroundBackground: TYPE - MACHINE DEPENDENT ( 
nun(O), blackOnWhite, whiteOnBlack, f irstAvailable, lastAvailable(255)}; 

DIP. Placement: TYPE = MACHINE DEPENDENT! 
null(O), sub, subSub, subSuper, super, superSub, superSuper, userSpecif ied, 
f i rstAvai 1 ab 1 e , 1 astAvai 1 ab 1 e ( 255 ) } ; 

DIP. Posture: TYPE - MACHINE DEPENDENT { 
null(O), upright, slanted, backslanted, f irstAvailable, lastAvailable(255)}; 

DIP.Serifness: TYPE = MACHINE DEPENDENT { 
null(O), serif, sansSerif, f irstAvailable, lastAvailable(255)}; 

DIP.Weight: TYPE = MACHINE DEPENDENT { 
null(O), ultralight, extraLight, light, semiLight, medium, semiBold, bold, 
extraBold, ultraBold, fi rstAvai 1 able, 1 astAvai 1 able (255)1; 

DIP. Width: TYPE = MACHINE DEPENDENT { 
proportional (0), quarter, third, half, threeQuarters, full, f irstAvailable, 
lastAvailable(255)}; 
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Appending Page Format Characters 

You can append a page format character to a document by calling 
DocInterchangeOef s.AppendPFC. This call will optionally return headings or 
footings that the client can fill in with calls to AppendText, 
AppendNewParagraph, or AppendChar. In addition, the client must specify 
page properties for the new PFC. 

DI. Heading: TYPE = LONG POINTER TO DI .HeadlngObject; 
DI.HeadlngObject: TYPE; 

DI. Footing: TYPE = LONG POINTER TO DI . FootingObject ; 
DI.FootingObject: TYPE; 

DIP.ReadonlyProps: TYPE = LONG POINTER TO READONLY DIP.PropsRecord; 

DI.AppendPFC: PR0C[ 
to: DI.Doc, 

pageProps : DIP. ReadonlyPageProps , 

wantHeadingHandles , wantFootlngHandles: BOOL <- FALSE, 

fontProps: DIP.ReadonlyFontProps <- NIL] 

RETURNS[ 

leftHeadlng, rlghtHeadlng : DI. Heading, 
leftFootlng, rightFootlng : DI. Footing]; 
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Appending Page Format Characters (cont'd) 

If you specify a heading or footing, you must call the corresponding release 
procedures, DocInterchangeDefs.ReleaseHeadlng and 
DocInterchangeDefs.ReleaseFooting, to insure against space leaks. Even if 
you do not append any information to the headings or footings, they must 
still be freed. 

DI.ReleaseHeadIng: PR0C[head1ngPtr: LONG POINTER TO DI. Heading]; 
DI.ReleaseFooting: PROC[f ootingPtr: LONG POINTER TO DI. Footing]; 
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Specifying Page Format Character Properties 
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Specifying Page Format Character Properties (cont'd) 

There are a large number of PFC properties that you can specify, but not all 
features are implemented. 

DIP.PageProps: TYPE = LONG POINTER TO DIP. PagePropsRecord ; 
DIP.ReadonlyPageProps: TYPE = LONG POINTER TO READONLY DIP. PagePropsRecord; 

DIP. PagePropsRecord: TYPE = RECORD[ 
pageDi'ms: DIP. PageDims , -layout 
topMarginHeight , bottomMarginHelght , 
leftMarginWidth, rightMarginWidth: CARDINAL, 
s tart 1ng Pages 1de: DIP. PageSide. 
b1nd1ngMarg1nW1dth: CARDINAL. 
nColumns: CARDINAL, - column structure 
balancedCol umns , unequalColumnWIdths: BOOL, 
columnSpadng: CARDINAL, 
columnWIdths: DIP.ColumnWIdths, 
startlngPageNumber: CARDINAL, - page numbering 
pageNumber Format: DIP.NumberFormat, 
restartPageNumberlng: BOOL, 
s tart 1 ng L 1 neNumbe r , -- line numbering 
llneNumberlnterval : CARDINAL, 
1 1 neNumbe r Format: DIP.NumberFormat, 
1 IneNumberLocatlon: DIP.LIneNumberLocatlon, 
headtngStartsOnThlsPage, headlngSameOnLef tRIghtPages, 
foot1ngStartsOnTh1sPage,foot1ngSameOnLef tRIghtPages: BOOL, 
sparel: LONG CARDINAL]; 
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w Specifying Page Format Character Properties (cont'd) 

DIP.PageDlms: TYPE = MACHINE DEPENDENT RECORD[w. h: CARDINAL]; 

DIP.PageSlde: TYPE = MACHINE DEPENDENT { 
nn(0), left, right, firstAvailable, lastAvanable(255)}; 

DIP. Number Format: TYPE = MACHINE DEPENDENT C 
cardinal (0) , lowerCaseLetter, upperCaseLetter, lowerCaseRoman, 
upperCaseRoman, firstAvailable, lastAvailable(255)}; 

DIP.LineNumberLocation: TYPE * MACHINE DEPENDENT { 
leftMargln(O), rightMargin, outerMargin, bothMargins, firstAvailable, 
lastAvailable(255)}; 

DlP.ColumnWidths: TYPE = LONG POINTER TO DIP.ColumnWidthsRecord; 

DIP.ColumnWidthsRecord: TYPE = RECORD[ 
length: CARDINAL, 
W sparel: LONG CARDINAL, 

widths:SEQUENCE max Length: CARDINAL OF DIP.ColumnWidthRecord] ; 

DIP.ColumnWidthRecord: TYPE = RECORD[ 
w: CARDINAL, 
sparel: LONG CARDINAL]; 
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Appending Frames 

Some of the types of anchored frames that you will typically append to a 
document are: bitmaps, graphics, and tables. DoclnterchangeDefs allows to 
you append these frames to a document but does not allow you to specify 
their content. Each of these objects has a separate interface for 
manipulating its content; graphics and table frames will be discussed in 
detail later. 

DI .AppendAnchoredFrame: PROC[ 
to: DI.Doc, 

type: OI.AnchoredFrameType, 

anchoredPrameProps : DI . ReadonlyFrameProps , 

content: DI. Instance InstanceNIl, 

wantTopCaptlonHandl e , wantBottomCaptionHandl e , 

wantLef tCaptlonHandle, wantRlghtCaptlonHandle: BOOL FALSE, 

anchorFontProps: DIP.ReadonlyFontProps <- NIL] 

RETURNS[ 

anchoredFrame : DI. Instance, topCaptlon, bottomCaption , 
leftCaptlon, rightCaptlon: DI. Caption]; 

DI.AnchoredFrameType: TYPE » MACHINE DEPENDENT { 
nn(0), bitmap, cuspButton, equation, graphics, IMG, table, text, illustrator, 
f i rstAvai 1 abl e , 1 astAvai 1 abl e ( 255 ) } ; 

DI. Caption: TYPE = LONG POINTER TO Dl.CaptionObject; 

DI.ReleaseCaptlon: PROC[captionPtr: LONG POINTER TO DI. Caption]; 
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Frame Properties 



All frames have a set of properties that are described by the 
DoclnterchangePropsDefs interface. Objects that have frames include: 
graphics, tables, and charts. 
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Frame Properties 

DIP.FrameProps: TYPE = LONG POINTER TO DIP. FramePropsRecord ; 

DIP.ReadonlyFrameProps: TYPE = LONG POINTER TO READONLY DIP. FramePropsRecord; 

DIP. FramePropsRecord: TYPE = RECORD[ 
borderStyle: DIP.BorderStyle. 
borderThlckness: CARDINAL, 

f rameD i ms : D I P . F r ameD i ms . -type = record [w. h: cardinal] 
flxedWidth, fIxedHelght: BOOL, 
span: DIP. Span, 

vertical Al ignment: DIP. Vertical Al ignment, 
horizontalAl ignment: DIP.Horizontal Al ignment, 
topMarginHeight, bottomMarginHeight, 
leftMarginWidth. rightMarginWidth: CARDINAL, 
sparel: LONG CARDINAL]: 

DIP.BorderStyle: TYPE = MACHINE DEPENDENT {invislble(O) , 
solid, dashed, broken, dotted, double, f IrstAvallable, lastAvailable(255)}; 

DIP.HorizontalAllgnment: TYPE = MACHINE DEPENDENT { 
left(O), centered, right, floating, f irstAvailable, lastAvailable(255)}; 

DIP. Span: TYPE = MACHINE DEPENDENT {parti al Col umn (0) , 
fullColumn, partialPage, fulTPage, f irstAvailable, lastAva11able(255)}; 

DIP. VerticalAl ignment: TYPE = MACHINE DEPENDENT { 
top(O), bottom, floating, f irstAvailable, lastAvailable(255)}; 



Note: All dimensions are in 1/72 inch. 
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Modes 

The mode of a document determines the way the information is displayed 
to the user (e.g. structure showing, cover sheet, etc.). You can retrieve and 
modify the document's mode as an assistance to the user. 

DI.GetModeProps: PROC[doc: DI.Doc, modeProps: DIP.ModeProps] ; 

DI.SetModeProps: PROC[ 
doc: DI.Doc, 

modeProps : DIP. ReadonlyModeProps , 
selections: DIP.ModeSelectlons]; 

DIP.ModeProps: TYPE = LONG POINTER TO DIP.ModePropsRecord ; 
DIP. ReadonlyModeProps: TYPE = LONG POINTER TO READONLY DIP.ModePropsRecord; 

DIP.ModePropsRecord: TYPE = RECORD! 
structureShowl ng , nonPr i nt i ngShowl ng , 
coverSheetShowing, promptFields: BOOL, 
sparel: LONG CARDINAL]; 

DIP.ModeSelectlons: TYPE = 
PACKED ARRAY DIP.ModeElements OF DIP.BooleanFalseDefault; 

DIP.ModeElements: TYPE « { 
StructureShowl ng, nonPr1nt1ngShow1ng, coverSheetShowing, promptFields, 
sparel, spare2, spare3, spare4, spares, spare6, spare?, spareS}; 

DIP.BooleanFalseDefault: TYPE « BOOL ^ FALSE; 
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Constants and Defaults 

DoclnterchangePropsDefs provides a set of constants that you can use to 
initialize property records with "neutral" values. In most cases, each value is 
the same as what would be set by the corresponding Get*PropsDef aul ts 
operation. 

DIP. nul 1 FrameProps: DIP. FramePropsRecord = [ ]; 

DlP.nuHPageProps: DIP. PagePropsRecord = [ ]; 

DIP.nu11Co1umnW1dth: DIP.Col umnWIdthRecord = 
DIP.nullFieldProps: DIP. Fiel dPropsRecord = [...]; 

DIP.nullFontProps: DIP. FontPropsRecord = [ ]; 

DIP.nullFontDescrlption: DIP. FontDescr1pt1on = [•••]: 
DIP.nullRun: DIP. Run = [...]: 
DIP.nullParaProps: DIP.ParaPropsRecopd = [...]; 
DIP.nullBaslcProps: DIP.BaslcPropsRecord = [•••]• 
DIP.nullTabStop: DIP.TabStop = [..-]: 
DIP.nullModeProps: DIP.ModePropsRecord = [...]: 

DIP. classic: Family = century; 
DIP. modern: Family = frutlger; 

DIP.GetFramePropsDef aul ts: PROC[props: DIP. FrameProps] ; 
DIP.GetPagePropsDefaults: PROC[props: DIP. PageProps] ; 
DIP.GetFleldPropsDef aults: PROC[props: DIP.FIeldPrpps]; 
DIP.GetFontPropsDefaults: PROC[props: DIP. FontProps]; 
DIP .GetParaPropsDef aul ts : PROC[props : DIP . ParaProps] ; 
DIP. GetModePropsDef aults: PROC[props: DIP.ModeProps]; 
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Additional Append Comments 

• The append procedures often allow font, paragraph, frame, or page 
properties to be set; however, if you default these arguments, then the 
properties of the preceding object will apply to the new object being 
appended. 

• The client must manage the storage required for arguments passed into 
the append procedures (this does not apply to handles that 
Dodnterchange returns to the client). When an append procedure 
returns, the client may release the storage allocated for any arguments. It 
is important that the client release non-NiL handles obtained from 
append procedures even if they were not used. 

• The ERROR DocInterchangeDefs. Error can be raised by any operation. If 
this error is raised by an Append* procedure, the object will not be 
appended. 

DI. Error: ERROR[why: DI . ErrorCode] ; 

DI.ErrorCode: TYPE = MACHINE DEPENDENT { 

contai'nerFul 1 (0) , documentFul 1 » readonlyDoc, outOfDIskSpace , 
outOfVM, objectll legal InContainer, badParameter , 
unlmplemented, f 1 rstAvallable, 1astAva1]ab1e(255)} 
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Finishing Creation 

After you have called StartCreation and maybe appended some 
information to the document, you should either finish the creation process 
or abort the uncompleted document. Clients can also invoke a call-back 
procedure before finishing the document creation process; this call-back has 
the power to abort the document's creation. 

DI.FinishCreation: PROC[ 

docPtr: LONG POINTER TO DI.Doc, 
checkAbortProc: DI .CheckAbortProc ^ NIL, 
checkAbortClientOata: LONG POINTER ^ NIL] 
RETURNS[ 

docF11e: NSF 11 e. Handle, 

session: NSF1 le. Session , 

status: DI. FlnlshCreationStatus]; 

DI.AbortCreatlon: PROC[docPtr: LONG POINTER TO DI.Doc]; 

DI.FinishCreationStatus: TYPE = MACHINE DEPENDENT { 
ok(0), aborted, okButNotEnoughDIskSpaceToPaginate, okBuNotEnoughVMToPaginate, 
okButUnknownPagi nateProbl em , f 1 rstAvai 1 abl e , TastAvai 1 able (255) } ; 

DI. CheckAbortProc: TYPE = PROC[cl ientData: LONG POINTER] 
RETURNS[abort: BOOL]; 
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Finishing Creation (cont'd) 

The NSFile handle, docFile, that is returned by FinishCreation is a 
temporary NSFile and will be purged at the next system boot unless it is 
made permanent. To make the file permanent, the file should be moved to 
the desktop and the desktop should be given a reference to the file. 

NSF11e.Move: PROC[ 

file: NSFile. Handle, destination: NSFile. Handle, 

attributes: NSFile. AttrlbutesLlst <- NSFile. nullAttrlbuteLlst, 

session: NSFile. Session NSFile. nuHSession]; 

StarDesktop. AddRef erenceToOesktop: PROC[ 
reference: NSFi 1 e . Reference , 
place: Window. Place StarDesktop. nextPl ace]; 

You will see an example of this in upcoming slides. 
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Document Enumeration 

DoclnterchangeDef s not only provides procedures for creating documents; 
it also allows you to enumerate the objects within an existing document. 
Before you can enumerate, you must call DoclnterchangeDef s. Open to get a 
handle to the document and prepare the file for enumeration. Open allows 
you to specify a session argument for background processing. The password 
argument is not currently supported. 

Dl.Open: PROC[ 

docFileRef: NSFile. Reference, 
session: NSFi 1 e .Session ^ NSFile. nul ISession , 
password: XString . Reader ^ NIL] 
RETURNS[doc: DI.Doc. status: DI .OpenStatus] ; 

Dl.OpenStatus: TYPE = MACHINE DEPENDENT { 
ok(0), malFormed, Incompatible, notLocal, outOfDIskSpace, outOfVM, 
busy.invalidPassword, f irstAvailable, lastAvailable(255)}; 
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Document Enumeration (cont'd) 

Once you have opened the document, you can call 
DocInterchangeDefs . Enumerate; this requires a set of procedures that it can 
call for each object in the document. If a procedure is left defaulted to NIL, 
then objects of that type are ignored. The cl ientData parameter in the call 
to Enumerate is used to pass data between the client defined enumeration 
procedures. 

DI. Enumerate: PROC[ 

textContalner : DI .TextContainer , 
procs: DI.EnumProcs, 
cl IentData: LONG POINTER <- NIL] 
RETURNS[dataSlcipped: BOOL]: 

DI.EnumProcs: TYPE = LONG POINTER TO DI.EnumProcsRecord; 

DI.EnumProcsRecord: TYPE « RECORD [ 
anchoredFrameProc: DI.AnchoredFrameProc N^IL, 
columnBreakProc: DI.ColumnBreakProc NIL, 
fieldProc: DI.FieldProc NIL, 
newParagraphProc: DI.NewParagraphProc NIL, 
pageBreakProc: DI.PageBreakProc NIL, 
pfcProc: DI.PFCProc ^ NIL, 
textProc: DI.TextProc NIL, 
tileProc: DI.TileProc NIL, 

sparelProc: Dl.SpareProc *■ NIL, spare2Proc: Dl.SpareProc NIL, 
spare3Proc: Dl.SpareProc NIL, spare4Proc: Dl.SpareProc NIL]; 
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Document Enumeration (cont'd) 

When the client supplied call-back procedures are invoked, they have all the 
properties for the particular object passed in. These procedures can then use 
this information for pattern matching, building another document, etc. The 
client cannot modify the document or any of the arguments passed in to the 
enumerate procedures; the enumerated information is read-only and valid 
only for the duration of the call. 

When any of the call-back procedures returns stop = TRUE, the 
enumeration stops. 

DI.NewParagraphProc: TYPE = PROC[ 
cHentData: LONG POINTER, 
fontProps: DIP. ReadonlyFontProps , 
paraProps: DIP.ReadonlyParaProps] 
RETURNS[stop: BOOL <- FALSE]; 

DI.PageBreakProc: TYPE = PROC[ 
clientData: LONG POINTER. 
fontProps : DIP. Readonly FontProps] 
RETURNS[stop: BOOL FALSE]; 

DI.TextProc: TYPE = PROC[ 
ClientData: LONG POINTER, 
fontProps : DIP. Readonly FontProps , 

text: XStrlng. Reader, textEndContext: XStn'ng. Context] 
RETURNS[stop: BOOL «- FALSE]; 
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Document Enumeration (cont'd) 

Some of the enumerate procedures return text containing objects (e.g. 
fields and PFCs), which can also be enumerated. NIL values are returned for 
objects that were never allocated (such as headings or footings). Since the 
client does not own the storage for these text containers, it is not necessary 
to release them when finished. 

DI.FieldProc: TYPE = PROC[ 
clientData: LONG POINTER, 
f ontProps : DIP. Readonly FontProps , 
f iel dProps : DIP . ReadonlyFiel dProps , 
field: DI. Field] 
RETURNS[stop: BOOL FALSE]; 

DI.PFCProc: TYPE = PR0C[ 
ClientData: LONG POINTER, 
f ontProps : DIP. Readonly FontProps , 
pageProps: DIP.ReadonlyPageProps, 
leftHeading, rIghtHeading : DI. Heading, 
leftFooting, rIghtFootIng : DI. Footing] 
RETURNS[stop: BOOL <- FALSE]; 

DI.AnchoredFrameProc: TYPE = PR0C[ 
ClientData: LONG POINTER, 
type: DI . AnchoredFrameType , 
anchor FontProps : DIP. Readonly FontProps , 
anchoredFrame: DI. Instance, 
anchoredFrameProps : DIP. ReadonlyFrameProps , 
content: DI. Instance. 

topCaption. bottomCaption , leftCaptlon, 
rightCaption : DI. Caption] 
RETURNS[stop: BOOL ^ FALSE]; 
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Document Enumeration (cont'd) 

When Enumerate returns, the client will generally close the document to 
release any storage associated with the document handle and to allow 
other clients to access the file. Cl ose sets docPtrt to NIL. 

DI. Close: PROC[docPtr: LONG POINTER TO DI.Doc]; 
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Document Example 

This sample program enumerates a selected document and copies its fields 
into a newly created document. When the enumeration is complete, the 
new document is saved and placed on the desktop and the original is closed. 
Since fields and PFC characters may contain additional information, the 
program must recursively copy their content as well. 



-- Copyright (C) Xerox Corporation 1986. All rights reserved. 

DIRECTORY 
Attention, 
BWSZone, 
Heap, 

DocInterchangeDef s , 

MenuData, 

NSFHe. 

Selection, 

StarDesktop, 

Window, 

XString; 

CopyDoc: PROGRAM 

IMPORTS Attention, BWSZone, DocInterchangeDefs, Heap, MenuData, NSFile, 
Selection, StarDesktop, XString = { 

FileProblem: SIGNAL = CODE; 

~ used for passing a text container (via clientData) to call- back procs 

ContainerPtr: TYPE * LONG POINTER TO DocInterchangeDef s.TextContainer; 

— call-back procedures called when enumerating a document 
enumProcs ; DocInterchangeDefs . EnumProcs Record [ 

fieldProc: FieldProc, 
newParagraphProc: NewParagraphProc, 
pageBreakProc: PageBreakProc, 
pfcProc: PFCProc, 
textProc: TextProc]; 

- simply add the copy document command to the attention menu 
In1t: PROG » { 

copyDoc: XString.ReaderBody XString.FromSTRING["Copy Documenf'L]; 
Attent ion. AddMenu I tern [ 
MenuData. Createltem[ 

zone: BWSZone. permanent, 

name: @copyDoc, 

proc: Copy] ]; 
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- enumerate through the selected document and copy the contents to a new document 
Copy: MenuData.MenuProc = { 

ref: NSFile. Reference OpenSelectedFi1e[ IFileProblem => GOTO Exit]; 

newFile: NSFile. Handle; 

oldDoc, newDoc: DocInterchangeDefs.Ooc; 

status : DocInterchangeDef s . OpenStatus ; 

f i ni shStatus : DocInterchangeDef s . Fi ni shCreati onStatus ; 

textContai ner : Doc I nterchangeDef s • TextContai ner ; 

[oldDoc, status] DocInterchangeDefs.Open[docFileRef :ref ] ; 
IF status # ok THEN GOTO Exit; 

" create new document and begin copying the old one 
newDoc ^ DocInterchanqeDefs.StartCreationf1.doc ; 
textContai ner [doc[h: newOocj]; 
[] DocI nterchangeDef s. Enumerate [ 

textContai ner: [doc[h: oldDoc]], 

procs: ^enumProcs, 

clientData: @textContainer] ; 

DocInterchangeDef s.ClosefdocPtr; goldPoc] ; 
[newFile« .fini shStatus] ^ DocInterchangeDefs.FinishCreation f 
docPtr: @newDoc, checkAbortProc: DummyAbortProc] ; 

IF finishStatus # aborted THEN [ 
desktop: NSFile. Handle ^ NSFile.OpenByReference[ 

StarDesktop.GetCurrentDesktopF11e[ ] ] ; 
NSFile. Move[file: newFile, destination: desktop]; 

StarDesktop.AddReferenceToDesktopI reference: NSFile.GetReference [newFile] ] ; 

NSFile. CloselnewFile]} 
ELSE DocInterchangeDef s.AbortCreation[docPtr: @newDoc]; 
EXITS Exit => NULL; 

^» Jose {kes^-hsf ^ 

DumniyAbortProc: Doc I nterchangeDef s. CheckAbortProc - {RETURN [FALSE]}; 

~ return a reference to the selected file. 

— If no file Is selected print a message and raise the error FileProblem 
OpenSelectedFile: PROC RETURNS[ref: NSFile. Reference] = { 

element: Selection. Value •*• Selection. Convert [target: file]; 
refPtr: LONG POINTER TO NSFile. Reference <■ element. value; 
IF refPtr = NIL THEN SIGNAL FileProblem; 
RETURN [ ref Ptr+]; 

}; 
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— copy the field passed in to the textcontainer specified by clientdata. 

— Since fields may contain information, recursively enumerate the contents of the field 
FleldProc: DocInterchangeDefs.FieldProc = { 

textcontainer: DocInterchangeDef s.TextContainer 

LOOPHOLE [ cl i entData , Contai nerPtr ] + ; 
newField; DocInterchangePefs, Field DocInterchanqeDefs«AppendFie1d[ 

to: textcontainer, 

fieldProps: fieldProps, 

fontProps: fontProps ! DocInterchangeDef s. Error *> GOTO bad]; 
" now enumerate any items within the field 

newTextContainer: DocInterchangeDef s.TextContainer [fie1d[h: newField]]; 
[] DocInterchangeDef s. Enumerate f 

textcontainer: [field[h: field]], 

procs: @enumProcs, 

clientData: ^newTextContainer] ; 
DocInterchangeDef s.ReleaseFieldf@newFie1d] ; 
EXITS bad ==> NULL; 

}; 

NewParagraphProc: DocInterchangeDef s.NewParagraphProc = { 
textcontainer: DocInterchangeDef s.TextContainer ■*■ 

LOOPHOLE [ c 1 i entData , Contai nerPtr ] + ; 
[] DocInterchangeDef s.AppendNewParaqraph f 
to: textcontainer, 
fontProps: fontProps, 

paraProps: paraProps IDocInterchangeDefs.Error => CONTINUE]; 

}; 

— will need to use a with statement to determine if doc or field 
PageBreakProc: DocInterchangeDefs.PageBreakProc = { 

textcontainer: DocInterchangeDef s.TextContainer 

LOOPHOLE [ c 1 i entData , Contai nerPtr ] + ; 
WITH z: textcontainer SELECT FROM 

doc => \] DocInterchangeDef s.AppendPaqeBreak f 
to: z.h, 

fontProps: fontProps IDocInterchangeDefs.Error CONTINUE]; 
ENDCASE; 

}; 

~ append the text passed in to the new text container 
TextProc: DocInterchangeDef s.TextProc = { 
textcontainer: DocInterchangeDef s.TextContainer 

LOOPHOLE[clientData, Contai nerPtr] +; 
DocInterchangeDef s .AppendText f 
to: textcontainer, 
text: text, 

textEndContext: textEndContext, 

fontProps: fontProps IDocInterchangeDefs.Error => CONTINUE); 

}; 
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PFCProc: DocInterchangeDefs.PFCProc = { 
textContainer: DocInterchangeDefs.TextContainer 

LOOPHOLE [c1 lentData, ContainerPtr ] + ; 
newLeftHeading, newRightHeading: DocInterchangeDefs. Heading; 
newLeftFooting, newRightFooting: DocInterchangeDefs. Footing; 
WITH z: textContainer SELECT FROM 

doc => { 

[newLeftHeading, newRightHeading, newLeftFooting, newRightFooting] 
DocInterchanqePefs.AppendPFC f 
to: z.h, pageProps: pageProps, 

wantHeadingHandles: (leftHeading # NIL) OR (rightHeading # NIL), 

wantFootingHandles: (leftFooting # NIL) OR (rightFooting # NIL), 

fontProps: fontProps ! DocInterchangeDefs. Error => GOTO bad]; 
IF leftHeading # NIL THEN { 
newTextContainer: DocInterchangeDefs. TextContainer ^ 

[ heading! h: newLeftHeading]]; 
[] DocInterchangeDefs. Enumerate f 

textContainer: [ heading (h: leftHeading] ] , 

procs: @enumProcs, 

clientData: @newTextContainer] ; 
DocInterchanqeDefs.Re1easeHeadinqf@newLeftHeadinq] l; 
IF rightHeading # NIL THEN { 
newTextContainer: DocInterchangeDefs. TextContainer 

[heading[h: newRightHeading]]; 
[] 4. DocInterchangeDefs. Enumerate I 

textContainer: [heading[h:rightHeading] ] , 

procs: ©enumProcs, 

ClientData: ©newTextContainer]; 
Doc InterchangeDef s . Rel easeHead i ng [ @newRi ghtHead i ng ] } ; 
IF leftFooting # NIL THEN { 
newTextContainer: DocInterchangeDefs. TextContainer * 

[footing! h: newLeftFooting]]; 
[] DocInterchangeDefs. Enumerate! 

textContainer: [ footing[h: leftFooting] ] , 

procs: @enumProcs, 

ClientData: ©newTextContainer] ; 
DocInterchangeDefs . Rel easeFoot i ng [ ©newLef tFoot i ng] } ; 
IF rightFooting # NIL THEN { 
newTextContainer: DocInterchangeDefs. TextContainer 

[footing[h: newRightFooting]]; 
[] DocInterchangeDefs. Enumerate! 

textContainer: [footing[h:rightFooting] ] , 

procs: ©enumProcs, 

ClientData: ©newTextContainer]; 
Doc I nterchangeDef s . Re 1 easeFoot i ng [ ©newRi ghtFoot i ng ] } } ; 
ENDCASE 
EXITS bad NULL 

}; 

— mainline code 
Init[]; 

^ * * * Jttitik. 
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Viewpoint Tables 

Tables simplify and organize information for the reader. In addition to 
presenting statistical and tabular information, tables can also be used for 
multiple column data, in which rows of information must stay together 
across columns. The number of rows and columns, column width and 
margins, and the widths and styles of ruling lines can ail be specified. 



Name 


College Graduate? 


Frank 


Yes 


Mark 


Yes 



Example of a table 
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Viewpoint Table Structure 

A table consists of individual cells that are organized into rows and columns. 
Cells are rectangular field-like areas that can be accessed with <NEXT> and 
have field settings. Cells can contain numbers and text. The row at the top 
of the table, called the header row, is used for labeling the columns of the 
table. 

A table resides in an anchored frame, which reserves space for the table in a 
document. A table can consist of a variety of rows, columns, repeating rows, 
divided columns, etc. 



Subdivided columns 



Header 
Row 
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liub-columns 

A table column can be dividec| into subcolumns either through the column 
property sheet or the docum ent auxiliary menu. In this example, a single 
column was divided into five' subcolumns. Each subcolumn has its own 
property sheet and can be further divided if desired. 





Test Scores 


Student 


- 


est 1 


Test 2 


Final 
Exam 


Wtd. 
Average 


Alison 




87 


79 


91 


' 87.00 


Byron 




66 


89 


84 


80.75 


Carlson 




45 


40 


98 


70.25 


Darvon 




90 


96 


32 


62.50 



Day 
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Sub-rows 

Subrows can be enabled within a column by using the column property 
sheet. Subrows can be added only to a divided column. 



Male Parent 


Children 




Lloyd Bridges 


Jeff Andrew 


Beau Timothy 


Brooke Lynn 


Harmon Katz 


Sherri 


Douglas 



In this table, the "Children" column has been 
made a divided column with only 1 subcolumn. 
Subrows were then added to this divided column. 
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Fill-in Rules 

Fill-in Rules make it possible to take information contained in one or more 
fields in a table and use that information to fill in other fields. The following 
are examples of fill-in rule usage: 

• Take information contained in a table and place it in another table. 

• Take various sets of figures in a table and perform computations on 
them. 
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Fill-in Rules Example 

In this example, the table calculates the wages to be paid to some 
employees. The AmountPaid column was filled in when the Update Fields 
command (from the document's auxiliary menu) was invoked. 



Employee 


Hourly Wage 


Hours 
Worked 


Amount Paid 


Jimmy Sue 


6.50 


40 


260.00 


Betty Lou 


4.25 


16 


68.00 


Bobby Jo 


7.90 


47 


398.95 


Peggy Ann 


28.00 


68 


2296.00 



Table Name: WagesZ 

Column 2 Name: HourlyWage -Column type = AMOUNT 

Column 3 Name: HoursWorked -Column type = AMOUNT 

Column4Name: AmountPaid -Column type = AMOUNT 

Fill-in Rule for 

AmountPaid Column: CHOOSE 

Wages2[THIS ROW] .HoursWorked <= 40 -> 
Wages2[THIS ROW] . HourlyWage * 
Wages2[THIS ROW] . HoursWorked ; 
OTHERWISE -> 

Wages2[THIS ROW] . HounyWage * 40 + 
Wages2[THIS ROW] .HourlyWage * 
(Wages2[THIS ROW] . HoursWorked - 40) * 
1.5 
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TablelnterchangeDefs 

TablelnterchangeDefs is the interface for accessing and manipulating tables 
in documents programmatically. With this interface and 
DoclnterchangeDefs, you can perform the following actions: 

• Create a new table 

• Read the contents of a table 

• Add information to a table 
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Your Guide to Table Structure 



TablelnterchangeDefs (Tl) defines the data structure for VP tables. This 
diagram shows some of the highlights of the beast: 



TI. Handle 



table 



TI. Object 



zone . . • 

table 

tableHelght, tableWldth 
rc 

sparel 
private 




RowContent 



rc is used as temporary 
storage when the client 
is appending rows. 



TI . RowContentSeq 



topMargin, bottomMargIn 
line 

vertical Al ignment 
sparel 



rowdata: SEQUENCE OF 
RowEntryRec 
subRows 

singleLineHint 

sparel 

content 
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Table Creation 

Call TablelnterchangeDef s.StartTable to create a new table: 

TI.StartTable: PROC[ 
doc: DI.Doc, 
props: TI .TableProps , 
c: Tl.Columnlnfo] 
RETURNS[h: TI. Handle]; 

doc is the document in which the table will be created, props and c describe 
the same characteristics as those that the user can set in the property sheets; 
these two parameters are defined later. 
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Opening an Existing Table 

Call TablelnterchangeDef s.StartExistingTable to obtain a handle to an 
existing table: 

TI.StartExistingTable: PROC[ 
table: DI. Instance, 
hi: TI.Headerlnfo NIL, 
rowPropsSource: NATURAL ^ 0, 
deleteExIstlngRows: BOOL ^ TRUE, 
numberOfRowsHint: NATURAL ^ 0] 
RETURNS[h: TI. Handle]; 

The parameter table (the table object) is often obtained from a call to 
TableSelectionDef s.TableFromSelection (TSD), which returns the current 
selection as a table. 

TSD.TableFromSelection: PROC RETURNS[DI . Instance] ; 

hi (header info) contains the desired properties for the table headers. When 
defaulted, the existing column headers are used. 

rowPropsSource is an index of a row in the table; this is the row from which 
row default properties are taken (rows are numbered from 0 - n). 

deleteExistingRows indicates whether the implementation should delete 
the contents of the table before adding new information. 

numberOf RowsHint is a hint about the number of rows that the table might 
contain; this helps the system allocate the space for the table. 
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Table Properties 

TablelnterchangeDef s.TableProps points to a record of table properties. 
These properties can be set by a user via table property sheets. 

TI.TableProps: TYPE = LONG POINTER TO TI.TablePropsRec; 

TI.TablePropsRec: TYPE = RECORD[ 
name: XString . Reader, 

filUnByRow, fixedRows, f ixedCol umns : BOOL, 
numberOf Col umns , numberOf Rows : NATURAL, 
vislbleHeader, repeatHeader, 
repeatTopCapti'on . repeatBottomCaptlon: BOOL, 
borderLine, dividerLine: TI.Line, 
horizontal A1 Ignment: TI .HeaderAl ignment, 
headerVertical Al ignment : TI .Vertical Al ignment , 
topHeaderMargin , bottomHeaderMargin: LONG CARDINAL, 
sortKeys: TI.SortKeys, 
sparel: LONG CARDINAL]; 

TLnullTableProps: TI.TablePropsRec = [...]; 
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Table Properties (cont'd) 

TI.HorizontalAlignment: TYPE = MACHINE DEPENDENT { 
1eft(0), center(l), right(2), decimal (3)]; 

TI.HeaderAllgnment: TYPE = TI. Horizontal Alignment [left •.right]; 

TI. Vertical Alignment: TYPE = MACHINE DEPENDENT { 
flushtop(O), centered(l), f lushbottom(2)}; 

TI.SortKeys: TYPE - LONG POINTER TO TI.SortKeysRec; 
TI.SortKeysRec: TYPE = RECORD! 

length: CARDINAL, 

sparel: LONG CARDINAL, 

keys: SEQUENCE maxLength: CARDINAL OF TI.SortKeyl; 

TI.SortKey: TYPE = RECORD [ 
columnName: XString. Reader, 
sortOrder: XString.SortOrder, 
ascending: BOOL, 
sparel: LONG CARDINAL); 

TI.nullSortKey: TI.SortKey = 1...1; 
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Table Properties (cont'd) 



I Defaults I Re 



TABLE PROPEPJIES 



^»Dorie I Apply f Cancel | Defaults | Reset !□ 



FRAME 


TABLED 


HEADER 


SORT KEYS 





Name 

Number of Rows 
Number of Columns 
Fill-in by 



Tablel 



FIXED 



FIXED 



VAR^llMa 



ROW 



Text Direction 



COWMH 



LEFT TO RIGHT 



RIGHT TO LEFT 



TABLE PROPERTIES 




A pply j Cancel || Defaults | Res et |n 



FRAME 


TABLE 


HEADER 


SORT KEYS 





Visibility 

Units 
Contents 



Text Direction 
Hpinht 



SHQW 



RepeatHeader Ruw orr Each Page 



Indies 



FLUSH LEFT 



CENTEREE>f 



GgNTERgD. 



L^E^TTG^Rr^E^Ti 



FLUSH RIGHT 



FLUSH TOP 



FLUSH BOTTOM 



horizontally 
vertically 



RIGHT TO LEFT 




DISPLAY 



FRAME 


TABLE 


HEADER 


SORT KEYS 





Sort Key List 



ASCENDIWG 


DESCENDING 


ASCBvIDilMG 


DESCENDING 
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Table Properties (cont'd) 



TABLE PROPERTIES 




Done 1 Apply f Cancel | Defaults f Reset i □ I g g 



DISPLAY IJjyiiiilall TABLE 


HEADER 


SORT KEYS 




Border Style 
Border Width 



























Units 
Margins 

Captions 
Width 
Height 
Alignment 



Inches 



Left 
Top 



.25 



Right 
Bottom 



.5 



LEFT 



RIGHT 



TOP 



BOTTOMj 



2.39 

.97 



FIXED 


VARYrWG 


FIXED 


VARYING 



FLUSH LEFT 


CENTERED 


FLUSH RIGHT 





IciiicLJT^^n I CI I ici_i Of-\Tr r-,h j\ 



horizontally 

..lis. 



TABLE RULING LINE PROPERTIES 




Done i Apply [□ i S 




Width 
Style 
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Header Properties 

TI.Headerlnfo: TYPE = LONG POINTER TO TI .Headerinf oSeq ; 

TI.HeaderlnfoSeq: TYPE = RECORD[ 

SEQUENCE length: CARDINAL OF TI.HeaderEntryRec]; 

TI.HeaderEntryRec: TYPE - RECORD! 
subheaders: TI.Headerlnfo, 
line: TI.Line, 
sing1eL1neH1nt: BOOL, 
spare 1: LONG CARDINAL, 

content : TI . EntryContent 1 ; EntryContent explained later 
TI.nullHeaderEntry: TI.HeaderEntryRec = (...1; 

TI.Line: TYPE « REC0RD[l1nestyle: TI.LInestyle, linewldth: TI.LInewidth] ; 

TI.Linestyle: TYPE - MACHINE DEPENDENT { 
none(O), solid, dashed, dotted, double, broken, fIrstAvallable, 
lastAva1lable(255)}; 

TI.LInewidth: TYPE = MACHINE DEPENDENT { 
wl(0), w2(l). w3(2), w4(3), w5(4), w6(5)}; 

TI.nullLlne: TI.Line * [llnestyle: solid, linewldth: wl]; 
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Appending Information to Tables 



Call TablelnterchangeDefs. AppendRow to add a row and its data toa table: 

TI.AppendRow: PROC[h: TI. Handle, rc: TI . RowContent] ; 

AppendRow adds the row described by rc to the table described by h, which 
was probably obtained from StartTable or StartExistingTable. 

The parameter rc is typically obtained from the rc field within the table 
object that h points to. In fact, the rc field within Object exists for that 
purpose: you fill in rc within Object and then call AppendRow. 

This procedure can raise the error Dl.Error[documentFun] if this row will 
not fit in the document. If this error occurs, clients are expected to CONTINUE 
the error and then make a call to FinishTable. 

TI. Error: SIGNAL[type: TI . ErrorType] ; 

TI.ErrorType: TYPE = MACHINE DEPENDENT { 

tableTooWide, tableHeaderTooTall , - can be raised by StartTable 
tableTooTall, — can be raised by AppendRow 
f i rstAvai 1 abl e . 1 astAvai 1 abl e( 255 )} ; 
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RowContent Structure 

TI.RowContent: TYPE = LONG POINTER TO TI.RowContentSeq; 

TI.RowContentSeq: TYPE = RECORD[ 

topMargIn, bottomMargin: LONG CARDINAL ^ 0, 
line: TI.Line *- [solid, w2], 

vertical A1 Ignment: TI .Vertical Al Ignment flushtop, 
sparel: LONG CARDINAL <- 0, 

rowdata: SEQUENCE length: CARDINAL OF TI . RowEntryRec] : 

TI.RowEntryRec: TYPE = RECORD[ 
subRows: TI.SubRows, 
slngleLlneHInt : BOOL, 
sparel: LONG CARDINAL, 
content: TI.EntryContent]; 

TI.nullRowEntry: TI.RowEntryRec = [ ]; 
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RowContent Structure (cont'd) 

TI.SubRows: TYPE = LONG POINTER TO TI.SubRowsRec; 

TI.SubRowsRec: TYPE = RECORD [ 
length: CARDINAL, 
sparel: LONG CARDINAL ^ 0, 

rows: SEQUENCE maxLength: CARDINAL OF TI • RowContent ] ; 

TI.EntryContent: TYPE = RECORD [ 
SELECT mode: * FROM 

read => [ --when enumerating 
obtai nTextProc : TI , Obtai nText Proc , 
obtainTextData: TI. Obtai nTextData] , 
write => [ " when appending a row 
filllnTextProc: TI.FminTextProc NIL, 
clientData: LONG POINTER NIL], 
ENDCASEl; 

TI. Obtai nTextProc: TYPE = PROC [obtai nTextData: TI. Obtai nTextData] 
RETURNSltext: Text InterchangeDefs. Text] ; 

TI. ObtainTextData: TYPE14]; 

TI. FilllnTextProc: TYPE -■= PROCl - client fills in text when called 
text: TextlnterchangeDefs.Text, clientData: LONG POINTER]; 
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RowContent Structure (cont'd) 



TABLE ROW PROPERTIES 



Done I Apply | Cancel [□ I s 



Display 



Row 


TEXT 





Units (s) 
Alignment 
Height 
Margins Top 



Inches 



FLUSHTOP 



CENTERED 



FLUSH BOTTOM 



.17 



.06 



Bottonn 



.06 



TABLE ROW PROPERTIES 




Display 



Row 



Line Height f 



TEXT 



ingle: 



1 1/2 



Double 



Triple 



Other 



Justified 



1 
t 
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Columnlnfo 

TablelnterchangeDef s.ColumnInf o points to a record containing a 
sequence of column properties. These properties can be set by a user via 
table property sheets. 

TI. Columnlnfo: TYPE = LONG POINTER TO TI .Col umnlnf oSeq ; 
Tl.ColumnlnfoSeq: TYPE = RECORD [SEQUENCE length: CARDINAL OF TI.ColumnlnfoRec] ; 

TI.ColumnlnfoRec: TYPE = RECORD [ 
headerEntryRec: TI .HeaderEntryRec, 
name, description: XStn'ng. Reader, 
divided: BOOL, 
subcolumns: NATURAL, 
repeating: BOOL, 
subcolumninf o: TI. Columnlnfo, 
alignment: TI .Horizontal Al Ignment, 
tabOffset, -Micas! (different from DIP.TabStop) 
width. leftMargln, rIghtMargin: LONG CARDINAL, 
type: DIP.FIeldCholceType, 
...]: 

Tl.nullColumnlnfo: TI.ColumnlnfoRec ~ [•••]: 
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Columnlnfo (cont'd) 



TABLE COLUMN PKOPEPJIES 



Done j Apply I Cancel i Defaults i Reset 



Display 



Column 


TEXT 


SORT KEYS 





Name 

Description 

Structure 

Contents 

Units 

Width 

Margins Left 

Type 

Format 

Range 

Length 



Table-I. 



Column2 



Divided 



FLUSH LEFT 



CEWTERED^ 



FLUSH RIGHT 



DECIMAL ALIGNED 



Inches 



1.19 



.06 



Right 



.06 



ANY 



TEXT 



AMOUNT 



DATE 



Required 



US ENGLISH 



Text Direction 



LEFT TO RIGHT 



RIGHT 1 



StopOnSkip 



characters or less 



TABLE COLUMN PROPERTIES 




Done i Apply i Cancel j Defaults in | s | 



Display 





TEXT 


SORT KEYS 





Name 

Description 

Structure 



Tablel. 



Column2 



Divided' 



Subcolumni 
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Finishing a Table 

You should call Tab1eInterchangeOefs.F1n1shTab1e when you are through 
editing a table. 

TI.FinishTable: PROC[h: TI. Handle] RETURNS[ 
table: DI. Instance, 

tableWidth, tableHelght: LONG CARDINAL]; "inmkas 

Pass table as the content argument to 
DocInterchangeDef s. AppendAnchoredFrame. FInlshTable deletes h.zone. 
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Read 



ng a Table 

You can read a table's content witHl TablelnterchangeDef |s 

TI.EnumerateTable: PROC[ 
tab1e:DI. Instance, 
procs: TI.EnumProcs, 
clientData: LONG POINTER nIIL] 



TI.EnumProcs: TYPE = LONG POINTER TO 

TI.EnumProcsRec: TYPE = RECORD [ 
tableProc: TI.TableProc NIL, 
columnsProc: Tl.ColumnsProc NIL, 
rowProc: TI.RowProc NIL]; 



Enumerate cails tableProc and co 

properties, respectively. Enumerat^ then calls rowProc fo 
table. 



1988 



I.EnumProcsRec; 



-•called once 
called once 

called for each row in table 



Enumerate. 



lumnsProc to get the jtalDle and column 

€Jach row in the 
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Enumeration Call-back Procedu 

TI.TableProc: TYPE = PROC[ 
clientData: LONG POINTER, 
props: TI .TableProps] 
RETURNS[stop: BOOL FALSE]; 

Tl.ColumnsProc: TYPE = PROC[ 
ClientData: LONG POINTER, 
columns: Tl.Columnlnfo] 
RETURNS[stop: BOOL <- FALSE]; 

TI.RowProc: TYPE = PROC[ 
ClientData: LONG POINTER, 
content: TI . RowContent] 
RETURNS[stop: BOOL <- FALSE]; 
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Enumeration Call-back Procedures 

There are a few different units of measurements in these interfaces and 
there will be times that you will need to convert between, for example, 
1/72s and micas. The interface UnltConverslon exists for this reason. 
UnitConversion has some predefined units and 2 convert procs that will 
convert integers or reals to whatever units you plug in to the procedures. 

UnitConversion. Units: TYPE = MACHINE DEPENDENT { 

inch(O), mm, cm, mica, point, pixel, pica, didotPoint, cicero. 

seventySecondOf Aninch , 1 ast( 15)}; 

~ point is a printer dot, pixel is a screen dot, pica = 12 points 

UnitConversion .Convertlnteger: PROC[ 
n: LONG INTEGER, 

inputUnit, outputUnits: UnitConversion .Units] 
RETURNS[LONG INTEGER]; 

UnitConversion. ConvertReal : PROC[ 
n: XReal .Number, 

InputUnit, outputUnits: UnitConversion. Units] 
RETURNS[XRea1 .Number]; 
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Table Example 

Here is an example of a basic program that runs from the Attention Menu, 
registers two commands: MakeTable, which creates a new document with 
table, and AddToTable, which adds four new rows to the selected table. 

DIRECTORY 
Attention, 
BWSZone, 

DocInterchangeDef s , 

DocInterchangePropsDef s , 

Heap, 

MenuData, 

NSFile, 

StarDesktop, 

TablelnterchangeDefs, 

TableSelectionDefs, 

TextlnterchangeDef s , 

XString; 

TableExample: PROGRAM 

IMPORTS Attention, BWSZone, DocInterchangeDef s. Heap, MenuData, NSFile, 
StarDesktop, TablelnterchangeDefs, TableSelectionDefs, TextlnterchangeDef s, 
XString = { 

tableWidth: CARDINAL = 1600; -micas 

headerMargin: CARDINAL - 35 * 9; - micas; margin should be 9 seventySecondsOfAnlnch 
rowMargin: CARDINAL = 100; 

< <Menu Proc for Create Table command. Creates new document, creates new table, appends table to 
document, and then adds document to desktop. > > 
MakeOocument: Menu Data. Menu Proc = { 

rows, columns: CARDINAL 3; -arbitrary 

doc: DocInterchangeDefs.DOC DocInterchangeDef s. StartCreation[ 1 .doc; 
table: DocInterchangeDef s. Instance - BuildSimpleTable[doc, rows, columns]; 
props: DocInterchangePropsDefs.FramePropsRecord 

DocInterchangePropsDef s . nu 1 1 FrameProps ; 
props. frameDims ^ [tableWidth, tableWidth]; 
[ ] DocInterchangeDef s.AppendAnchoredFramel 

to: doc, 

type: table, 

anchored FrameProps: ©props, 
content: table]; 
AddFi 1 eToDeskTop [ doc ] ; 

1; 
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< < Create table inside doc with specified number of rows and columns. The content will be the string 
'abc.">> 

BuHdSlmpleTable: PROC[doc: DocInterchangeDefs.Doc, rows, columns: CARDINAL] 
RETURNS [table: DocInterchangeDefs. Instance ^ DocInterchangeDefs.instanceNil ] = 

h: Tab! eInterchangeDefs. Handle; 

contentString: XString.ReaderBody XString.FromSTRING[ "abc"L] ; 
c: TablelnterchangeDefs.Columnlnfo BWSZone.shortLifetime.NEW[ 

TablelnterchangeDef s.ColumnInfoSeq[columns] ] ; 
props: TablelnterchanqePefs.TablePropsRec [ 

name: NIL, 

flllinByRow: TRUE. 

fixedRows: FALSE, 

fixedColumns: TRUE, 

numberOfColumns: columns, 

numberOf Rows : rows, 

visibleHeader: TRUE, 

repeatHeader: TRUE, 

repeatTopCaption: TRUE, 

repeatSottomCaption: TRUE, 

borderLine: [none, wl], 

dividerLine: [solid, w4], 

horizontalAlignment: center, 

headerVert 1 cal Al i gnment : centered , 

topHeaderMargin: headerMargin, 

bottomHeaderMarg 1 n : headerMarg i n , 

sortKeys: NIL, 

sparel: 0]; 
FOR 1: CARDINAL IN [0.. columns) DO 

c[il TablelnterchangeDef s.nullColumnlnfo; 

c[il. width tableWldth; 
ENDLOOP; 

— start creating table 

h TableInterchangeDefs.StartTable[doc: doc, props: ©props, c: c]; 
BWSZone . short Li f et ime . FREE [ @c ] ; 
~ set row props and content 
h.rc.topMargin rowMargin; 
h.rc.bottomMargin rowMargin; 
FOR i: CARDINAL IN [Crows) DO 
FOR j: CARDINAL IN [0.. columns) DO 
h.rc[jl - [ 

subRows: NIL, 

singleLineHint: FALSE, 

sparel: 0, 

content: [write[fillInTextProc: FilllnText, 

clientData: ©contentString]] ]; 

ENDLOOP; 

TableInterchangeDefs.AppendRow[h, h.rc] ; 
ENDLOOP; 

RETURN[TableInterchangeDefs.FinishTable[h]. table]; 

}; 
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FininText: Tab! eInterchangeDefs. Fill InTextProc = [ 
<<PROC[text: TextlnterchangeDefs.Text, clientData: LONG POINTER]; >> 

r: XStrlng. Reader NARROW [cHentDat a, XStr ing. Reader 1 ; 

Text InterchangeDef s . AppendTextToText [ 
to: text, text: r, textEndContext: XString.unknownContext] ; 

}; 

< < Menu Proc for Add To Table command. Just adds four new blank rows to selected table, > > 
AddToTable: MenuData.MenuProc - { 
h: TablelnterchangeDefs. Handle NIL; 

table: DocInterchangeDefs. Instance = Tab1eSelectionDefs.Tab1eFromSe1ection[ ] ; 
— if current selection is not a table, then return. Otherwise, add new rows to it. 
" If doc is not editable, then return. 

IF table = DocInterchangeDefs. instanceNil THEN RETURN 
ELSE { 

h TablelnterchangeDefs. StartExistingTable[ 

table: table, deleteExistingRows: FALSE -catcherrorif doc is not editable 

I TablelnterchangeOefs.TableError => GOTO Exit]; 
THROUGH [0..4) DO 

TableInterchangeDefs.AppendRow[h, h.rc] ; 
ENDLOOP; 

}; 

[] TableInterchangeDefs.FinishTable[hI; 
EXITS Exit => NULL; 

}; 

AddFUeToDeskTop: PROCldoc: DocInterchangeDefs. Doc] = { 
docFile: NSFile. Handle ^ DocInterchangeDefs. FinishCreation[@doc] .docFile; 
refDoc: NSFile. Reference = NSFile.GetReference[docFile] ; 
refDt: NSFile. Reference = StarDesktop.GetCurrentDesktopFile[ ] ; 
fileDt: NSFile. Handle = NSFile.OpenByReference[refDt] ; 
NSFile.Move[docFile, fileDt]; 
NSFile. CloselfileDt]; 
NSFile. CloseldocFile}; 
StarDesktop . AddRef erenceToDesktop [ refDoc ] ; 

}; 

Init: PROC - { 

makeTable: XString.ReaderBody ^ XString.FroniSTRING[ "MakeTable"L] ; 
addToTable: XString.ReaderBody XString.FromSTRINGI "AddToTable" L] ; 
Attent ion. AddMenu I tern [ MenuData . Create I tern [ 

zone: BWSZone. permanent, 

name: @makeTable, 

proc: MakeDocument ] ] ; 
Attention .AddMenu I tern [ MenuData . Createltem[ 

zone: BWSZone. permanent, 

name: @addToTable, 

proc: AddToTable]]; 

}; 

In1t[]; 
}... 
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Viewpoint Graphics 

Viewpoint graphics must appear in a graphics frame. The following is a 
graphics frame with all possible graphics objects (except an image frame 
and CUSP button): 



Text Frame Form Field Graphics Frame Bitmap Frame 

r O O 
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What's GraphicslnterchangeDefs For? 

GraphlcsInterchangeDef s is the main interface for creating and 
enumerating grapliics programmatically in ViewPoint. It is used in 
conjunction with DoclnterchangeDef s to both add and enumerate graphics 
in VP documents. It uses types defined in DocInterchangePropsDef s and 
other interfaces. 

In the following slides, Gl may be substituted for GraphicslnterchangeDefs, 
Dl may be substituted for DoclnterchangeDefs, and DIP for 
DoclnterchangePropsDefs. 
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Adding Graphics to a Document 

Graphics can be added to a document only during the process of a 
DocInterchangeDef s.StartCreatlon. Graphics cannot be appended to an 
existing document. 

Use the following steps to append graphics to a new document. Each step is 
covered in more detail on the following pages: 

1. Call DI .StartCreatlon to get a document handle (doc). 

2. Call GI .StartGraphlGs[doc] to get an anchored frame handle (h). 

3. Call GI . Add*[h] to add graphics to that anchored frame. 

4. If you want to add a container to the anchored frame: 

A, Call GI .StartGraphicsFrame, GI .StartCluster, or GI .StartButton 
to get a handle for the container (gf h, ch, or bf h). 

B, Call GI . Add*[gf h, ch, or bf h] to add graphics to the container. 

C, Call GI . FInlshGraphlcsFraroe, GI . FInlshCI uster, or 
GI.FInlshButton. 

5. Call Gl.FinishGraphics[h] to complete the anchored frame and get an 
object of type DI. Instance (graphics). 

6. Call DI.AppendAnchoredFrame[graph1cs]. 

7. Call DI.F1n1shCreat1on[@doc]. 
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Starting a Graphics Frame ^ 

Call GraphicslnterchangeDefs. StartGraphlcs to create a graphics frame: 

GI.StartGraphlcs: PROC[doc: DI.Doc] RETURNS[h: GI. Handle]; 

GI. Handle: TYPE = LONG POINTER TO GI. Object; 
G I. Object: TYPE; 

The returned handle points to an opaque type. The handle is used by other 
procedures to add objects to the graphics frame. 
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Starting a Nested Frame 

Among the objects that can be added to a graphics frame are nested frames. 
A Handle for each of these frames allows the client to add objects to the 
nested frames later. This Handle is of the same type returned by 
StartGraphlcs. The return parameters are the handle to the nested frame 
and the handles to any captions the caller wanted. 

1. Call GraphlcsInterchangeDef s.StartGraphlcsFrame to create a nested 
graphics frame: 

GI.StartGraphlcsFrame: PROC[ 
h: GI. Handle, 
box: GI.Box, 

f rameProps : GI . ReadonlyFrameProps . 

name, description: XStrlng. Reader <- NIL, -extra props Jike tables 
spareProps: LONG POINTER NIL. 
wantTopCaptlonHandle, wantBottomCaptlonHandle, 
wantLeftCaptlonHandle, wantRlghtCaptlonHandle: BOOLEAN ^ FALSE] 
RETURNS[ 

gfh: GI. Handle, 

topCaptlon, bottomCaptlon , 

leftCaptlon, rIghtCaptlon : DI. Caption]; 

h is the handle to the anchored graphics frame in which this nested frame 
will reside. 

box is the size and frame-relative location of the nested frame. Units are 
specified in micas. 
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Frame Properties 

All frames have frame properties. These properties define the border, 
margins, caption capabilities, and expansion properties of a frame. 

GI.FrameProps: TYPE LONG POINTER TO GI . FramePropsRec; 

GI.ReadonlyFrameProps: TYPE = LONG POINTER TO READONLY G I. FramePropsRec; 

GI. FramePropsRec: TYPE = RECORD[ 
brush: GI. Brush, 
fIxedShape: BOOL, 

margins: ARRAY Gl.Slde OF LONG CARDINAL, 
captionContent: ARRAY Gl.Slde OF DI. Caption, 
sparel: LONG CARDINAL]; 

captionContent is ignored in all Add* operations and is only meaningful 
during enumeration. 

61. Brush: TYPE = RECORD [ 
wthBrush: LONG CARDINAL, - width of the brush in micas 

styleBrush: GI.StyleBrush] ; 

GI.StyleBrush: TYPE = MACHINE DEPENDENT { 
invisible(O), solid(l). dashed(2), dotted(3), double(4), broken(5), (15)}; 

Gl.Side: TYPE = {top, bottom, left, right}; 
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Starting a Nested Frame (cont'd) 

2. Call GraphlcsInterchangeDefs.StartCluster to create a set of cluster 
objects: 

Gl.StartCluster: PROC[h: GI. Handle, box: GI.Box] 
RETURNS[ch: GI. Handle]: 

h is the handle to the anchored graphics frame in which this cluster will 
reside. 

box is the size and frame-relative location of the nested frame. Units are 
specified in micas. 

ch is the handle to the cluster. Subsequent calls to add objects to the cluster 
will use ch. 
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Starting a Nested Frame (cont'd) 

3. Call GraphicslnterchangeDefs. StartButton to create a CUSP button in a 
graphics frame: 

GI. StartButton: PROC[ 
h: GI. Handle, 

box : G I . Box , — if buttonProps is NIL then a unique name is generated 
buttonProps: GI.ReadonlyButtonProps, 
f rameProps : GI . ReadonlyFrameProps , 
wantProg ramHandl e , wantTopCapt1onHand1 e • 
wantBottomCaptlonHandle, wantLef tCaptlonHandle, 
wantR1ghtCapt1onHand1e: BOOLEAN ^ FALSE] 
RETURNS[ 

bfh: GI. Handle, 

buttonProgram: GI .ButtonProgram, 
topCaptlon, bottomCaptlon, 
leftCapti'on, rightCaptlon: DI. Caption]; 

h is the handle to the anchored graphics frame in which this button will 
reside. 

box is the size and frame-relative location of the nested frame. Units are 
specified in micas. 

DI.ReadonlyButtonProps: TYPE = LONG POINTER TO READONLY DI.ButtonPropsRec; 

DI.ButtonPropsRec: TYPE * RECORD [ 
name: XString. Reader, 
sparel: LONG CARDINAL]; 

Note: Graphics objects may be inserted inside a button by calling the Add* 
procedures and passing the button handle (bfh). 
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Finishing Containers 

When you have finished adding objects to a container, you must call the 
appropriate procedure to notify the graphics implementation that you are 
not going to add any more objects. 



if your container was 
started with: 


...tlien flnisii it witli: 


StartGraphlcs 


F1n1shGraphics 


StartGraph i cs Frame 


FinishGraphicsFrame 


StartCluster 


FinishCluster 


StartButton 


FinishButton 



GI.FInishGraphlcs: PROC[h: GI. Handle] 

RETURNS[g raph 1 cs : DI . I nstance] ; - return instance to DLAppendAnchoredFrame 

GI. FinishGraphicsFrame: PROC[gfh: GI. Handle]; 

GI. FinishCluster: PROC[ch: GI. Handle]; 

GI. FinishButton: PROC[bfh: GI. Handle]; 
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Adding Objects to a Graphics Frame 

All of the following procedures add an object to a graphics frame (anchored 
or nested), button, or cluster, as defined by the handle passed in. A box 
parameter is also passed to each procedure that defines where the object 
should appear in the frame, button, or cluster. 

GI.AddPoint : PROCl 

h: GI. Handle, box: GI.Box, pointProps: GI.ReadonlyPointProps] ; 
GI .AddLine : PROC[h: GI. Handle, box: GI.Box, lineProps: GI.ReadonlyLineProps] ; 
GI.AddCurve : PROC[ 

h: GI. Handle, box: GI.Box, curveProps: GI.ReadonlyCurveProps] ; 
GI.AddEccentricCurve : PROCl 

h: GI. Handle, box: GI.Box, eccentricCurveProps: GI.ReadonlyEccentricCurveProps] ; 
GI.AddEllipse : PROCl 

h: GI. Handle, box: GI.Box, elUpseProps: GI.ReadonlyEllipseProps] ; 
GI.AddRectangle ; PROC[ 

h: GI. Handle, box: GI.Box, rectangleProps: GI.ReadonlyRectangleProps] ; 
GI.AddTrianqle ; PROC[ 

h: GI. Handle, box: GI.Box, triangleProps: GI.ReadonlyTriangleProps] ; 
GI .AddTextFrame : PROC[ 

h: GI. Handle, box: GI.Box, frameProps: GI.ReadonlyFrameProps, ...]; 
GI.AddFormField : PROC[ 

h: GI. Handle, box: GI.Box, fieldProps: GI.ReadonlyFieldProps, ...]; 
GI.AddBitmap ; PROC[ 

h: GI. Handle, box: GI.Box, bItmapProps: GI.ReadonlyBUmapProps. . . ] ; 
GI.Addlmage : PROC[ 

h: GI. Handle, box: GI.Box, imageProps: GI. Readonly ImageProps, ...]; 
GI . AddOther ; PROC[h: GI. Handle, box: GI.Box, instance: DI. Instance] ; 
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Box 

Ail GraphicslnterchangeDefs .Add* procedures take a 
GraphicslnterchangeDefs. Box as a parameter. This parameter specifies the 
location and size of the object to be appended. Note that most Add* 
procedures specify no dimensions for the object being added; in those cases, 
the dimensions are determined by box. Dimensions are specified in micas 
(roughly 35 micas/point). 

GI.Box: TYPE = RECORD [ -AGI.BoxissimilartoaWindow.BoxbutaWlndow.boxis 
p 1 ace : Gl.Place, dims: GI.DIms]; ~ specified in points not micas 

GI. Place: TYPE = RECORD[x. y: INTEGER]; 
GI.Dims: TYPE = RECORD[w, h: INTEGER]; 



Upper left 

corner 
of parent 



Increasing x 
^ 



100 



220 



Increasing y 

200 



320 




This circle (ellipse) being added to a graphics frame has a box of 
[[x: 1 00, y :200],[w: 1 20, h : 1 20]]. 



Note: it is illegal to specify negative width or height for a box. An object's 
pi ace should always indicate its upper left corner. 
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Adding a Point to a Graphics Frame 



A point is defined by its pol ntProps and its box within the frame. The fields w 
and h are ignored in the box specification. 

GI.AddPoint: PROC[ 

h: GI. Handle, box: GI.Box, pointProps: GI . ReadonlyPointProps] ; 

Gl.PointProps: TYPE = LONG POINTER TO G I. Point Props Rec; 
GI.PointPropsRec: TYPE = RECORD! 

wthbru Sh : CARD I NAL , » in micas (roughly 35 micaslpoint) 

pointStyle: Gl.PolntStyle round,-- shape of point 

pointFill: GLPointFilT solid, 

sparel: 0]; 

G I. null PointProps: GI.PointPropsRec *[...!; 

GI. PointStyle: TYPE = MACHINE DEPENDENT {solid(O), hollow(l), (255)}; 
GI. PointFill: TYPE = MACHINE DEPENDENT { 
round(O), square(l), triangle(2), cross(3), (255)}; 

wthbrush specifies the size in micas. The legal set of values for wthbrush is 
{35, 71, 106, 141, 176, 212}. Any other values used may be harmful to the 
health of the document. 



\ 



POINT PKOPEKTIES 



Size 

Style 

Form 




Done f Apply f □ f g | 
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Adding a Line to a Graphics Frame 

Aline is defined by its UnePropsand its box within the frame. 

GI.AddLine: PROC[ 

h: GI. Handle, box: GI.Box, llneProps: GI . ReadonlyLlneProps] ; 

GI.LineProps: TYPE = LONG POINTER TO GI.LinePropsRec; 
LinePropsRec: TYPE - RECORD! 
brush: GI. Brush, 

UneEndNW: GI.LIneEnd, - shape of line end 
lineEndSE: GI.LIneEnd, 

HneEndHeadNW: GI.LIneEndHead, - shape of arrow head, if line endisanarrow 
UneEndHeadSE: GI.LIneEndHead, 
direction: GI.LIneDlrection, 
fixedAngle: BOOL, 
sparel: LONG CARDINAL]; 

GI.LIneEnd: TYPE = MACHINE DEPENDENT { 

flush(O), square(l), round(2), arrow(3), (7)); 

GI.LIneEndHead: TYPE = MACHINE DEPENDENT {none(O), hl(l), h2(20, h3(3), (15)}; 

GI.LineDirection: TYPE = MACHINE DEPENDENT {WE(0), NS(1). NwSe(2), SwNe(3)}; 

UneEndNW and UneEndSE describe the shape of the ends of a line. 
1 ineEndNW describes the end that is in the West, North, or Northwest; West 
has precedence over North, i ineEndSE describes the end that is in the East, 
South, or SouthEast, where East has precedence over South (See Slide 4-17). 
If lineEnd* = arrow, then lineEndHead* describes the type of arrow. For 
example, if 1 ineEndNW = arrow, then 11 neHeadNW = hi, h2, or h3; otherwise, 
1 ineEndHead* is ignored. 
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Adding a Line to a Graphics Frame (cont'd) 

direction serves as either a constraint or a necessary parameter, depending 
on the type of line being added: 

1. If you want to add a horizontal line, then the height of the box must be 
zero. If you want this line to have the constraint of always being 
horizontal, then set di rectlon = WE; else, set it to NwSe or SwNe (doesn't 
matter which). 

2. If you want to add a vertical line, then the width of the box must be zero. 
If you want this line to have the constraint of always being vertical, then 
set dl rectlon = NS; else, set it to NwSe or SwNe (doesn't matter which). 

3. If you want a line other than horizontal or vertical, it will be a variation 
on one of the following: 




Case A Case B 



In Case A, set direction = NwSe. In Case B, set direction = SwNe. 

Any other combination of box dimensions and direction will result in 
potentially hazardous situations. 
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Adding a Line to a Graphics Frame (cont'd) 




A line where lineNW Is in the SW corner of its box. direction Is SwNe. 
The property sheet for this line Is also shown. 

For the above... 

myLlnePropsRec: GI . LInePropsRec [ 

brush: [176, solid], llneEndNW: square, UneEndSE: arrow, 
1 IneEndHeadNW: none, llneEndHeadSE: hi, direction: SwNe, 
fixedAngle: FALSE, sparel: 0]; 
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Adding a Curve to a Graphics Frame 



A curve is defined by its curveProps and its box within the frame. 

GI.AddCurve: PROC[ 

h: GI. Handle, box: GI.Box, curveProps: GI.ReadonlyCurveProps]; 

GI. CurveProps: TYPE = LONG POINTER TO GI.CurvePropsRec; 
GI.CurvePropsRec: TYPE = RECORD [ 

brush: GI. Brush, 

11neEndNW: GI.LineEnd, 

lineEndSE: GI.LineEnd, 

UneEndHeadNW: GI.LIneEndHead. 

1 1 neEndHeadSE : G I .Li neEndHead , 

direction: GI.LineDirection, - direction ignored, set to WE 

placeNW, placeApex, placeSE, placePeak: Gl.Place, - RECORD [x, y: integer] 
fixedAngle: BOOL, 
sparel: LONG CARDINAL]; 

place* defines the curve by specifying the endpoints, apex, and peak, 
place* is relative to the origin of curve's box . 



origin 
placeApex— 




placePeak 



- piaceSE 



placeNW 



The peak is the highest point on the curve; the apex is the intersection 
of the two tangents drawn from placeNW and placeSE. 
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Adding a Curve to a Graphics Frame (cont'd) 

Curves paint clockwise, where the NW point of a curve must be painted 
before the SE point. Can you identify the NW and SE points on the following 
curves? 
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Adding an Eccentric Curve to a Graphics Frame 

An eccentric curve is defined by its curveProps and its box within the frame. 
The curve is specified by its endpoints, apex, and eccentricity, eccentricity 
is a fraction whose value is treated as: 

eccentricity / LAST[CARDINAL] 

thereby allowing the highest precision for eccentricities from 0 - 1 . 

GI.AddEccentricCurve: PROC[ 
h: GI. Handle, 
box: GI.Box, 

eccentricCurveProps: GI .ReadonlyEccentricCurveProps]; 

GI.EccentricCurveProps: TYPE = LONG POINTER TO GI.EccentricCurvePropsRec; 
GI.EccentricCurvePropsRec: TYPE = RECORD! 

brush: GI. Brush, 

UneEndNW: GI.LIneEnd, 

lineEndSE: GI.LIneEnd, 

lineEndHeadNW: GI.LIneEndHead, 

lineEndHeadSE: GI.LIneEndHead, 

direction: GI.LineDirection, 

placeNW, placeApex, placeSE: G I. Place, - relative to ongin of curve's box 
eccentricity: CARDINAL, 
fixedAngle: BOOL, 
sparel: LONG CARDINAL]; 
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Adding a Rectangle to a Graphics Frame 

A rectangle Is defined by its rectangieProps and its box within the frame. 
Squares are a subset of rectangles. The dimensions of the rectangle 
correspond to the box size. 

GI.AddRectangle: PROC[h: GI. Handle, 

box: GI.Box, rectangieProps: GI.ReadonlyRectangleProps]; 

GI. RectangieProps: TYPE * LONG POINTER TO GI.RectanglePropsRec; 
GI.RectanglePropsRec: TYPE = RECORD[ 

brush: GI. Brush, 

shading: GI. Shading, 

fIxedShape: BOOL, 

sparel: LONG CARDINAL]; 




SHAPE PROPERTIES 




Done i Apply i Cancel f □ i s 



Line Width 
Line Style 
Shading 
Texture 
Appearance 

Constraint 



r» 1 1 1 1 IT 

I I IMIIi 

riTiTTTT 



Fixed Shape 



m 



A rectangle and its properties. These properties are the sanne for any polygon. 
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Shape Properties 

Ail polygons have similar properties that include a brush and shading 

GI. Brush: TYPE = RECORD! 
wthBrush: CARDINAL, -in micas 

sty 1 eSru sh : G I . Sty 1 eBru sh ] ; - invisible, solid, daslied, dotted, double, brolcen 

GI. Shading: TYPE = RECORD[gray: 61. Gray, textures: GI. Textures]; 

GI.Gray: TYPE = MACHINE DEPENDENT { 
none(O), gray25(l), gray50(2), gray75(3), black(4), (15)}; 

GI.Textures: TYPE = PACKED ARRAY GI. Texture OF BOOLEAN; 

GI. Texture: TYPE = MACHINE DEPENDENT { 
vertical (0), horizontal (1), nwse(2), swne(3), po1kadot(4) , (11)}; 
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Adding an Ellipse to a Graphics Frame 

An elipse is defined by its el 1 1pseProps and its box within the frame. Circles 
are a subset of ellipses. 

GI.AddElUpse: PROC[ 

h: GI. Handle, box: GI.Box, 

el 1 IpseProps: GI.ReadonlyE1 1 ipseProps]; 

GI.EnipseProps: TYPE = LONG POINTER TO GLElUpsePropsRec; 
GI.EnipsePropsRec: TYPE = RECORD! 

brush: GI. Brush, 

shading: GI. Shading, 

fIxedShape: BOOL, 

sparel: LONG CARDINAL]; 




An ellipse and its properties. Double border line style is not supported for ellipses. 
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Adding a Triangle to a Graphics Frame 

A triangle is defined by its triangleProps and its box within the frame. The 
triangle's dimensions are determined by their pi ace*, although the amount 
displayed is determined by box. 

GI.AddTrlangle: PROC[ 

h: GI. Handle, box: GI.Box, 
triangleProps: GI .ReadonlyTrlangleProps]: 

GI. TriangleProps: TYPE = LONG POINTER TO GI.TrianglePropsRec; 
GI.TrianglePropsRec: TYPE = RECORDl 

brush: GI. Brush, 

shading: GI. Shading, 

pi ace 1, placeZ, placeS: G I. PI ace, -corners of triangle relative to upper left of triangle's box 
fixedShape: BOOL, 
sparel: LONG CARDINAL]; 




SHAPE PROPERTIES 




Done 1 Apply 1 Cancel | □ 



Line Width 
Line Style 
Shading || II 



Texture 
Appearance 

Constraint 



H H m 



Fixed Shape 



A triangle and its properties. 
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Adding a Text Frame to a Graphics Frame 

A text frame is defined by its f rameProps and its box within the frame. 

GI.AddTextFrame: PROC[ 

h: GI. Handle, box: GI.Box, 

f rameProps : GI .Readonly F rameProps , 

textFrameProps: GI . ReadonlyTextFrameProps , 

wantTextHandl e , wantTopCapt lonHand 1 e , wantBottomCapt1onHand1 e , 
wantLef tCaptlonHandle, wantRlghtCaptlonHandle: BOOLEAN ^ FALSE] 
RETURNS[ 

text: TextlnterchangeDef s.Text, topCaptlon, 
bottomCaption, leftCaption, rlghtCaptlon: DI. Caption]; 

GI.FrameProps: TYPE * LONG POINTER TO GI.FramePropsRecord; 
GI.FramePropsRec: TYPE = RECORD! 

brush: GI. Brush, 

fIxedShape: BOOL, 

margins: ARRAY G I. Side OF CARDINAL, -micas 
capt1onContent:ARRAY Side OF DID. Caption, 
sparel: LONG CARDINAL]; 

G I. TextFrameProps: TYPE = LONG POINTER TO GI.TextFramePropsRec; 
GI.TextFramePropsRec: TYPE = RECORD [ 

expandRight, expandBottom, transparent: BOOL, 

tFrameProps: TextlnterchangeDefs.TFramePropsRec, 

sparel: LONG CARDINAL]; 

Specify want*Handl e for those objects to which you want to add text. 
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Adding a Form Field to a Graphics Frame 

A form field is defined by its f ieldProps and its box within the frame. 

GI.AddFormField: PROC[ 

ti: GI. Handle, box: GI.Box, fleldProps: DIP. Readon1yF1e1 dProps . 
f rameProps : GI . ReadonlyFrameProps . 
paraProps: DIP.ReadonlyParaProps NIL, 
fontProps: DIP. ReadonlyFontProps NIL, 
expandRlght, expandBottom: BOOL «- FALSE, 

wantFleldHandle, wantTopCaptlonHandle, wantBottomCaptlonHandle, 
wantLeftCaptionHandle, wantRightCaptlonHandle: BOOLEAN <- FALSE] 
RETURNS[ 

field: DI. Field, topCaptlon, 

bottomCaptlon, leftCaptlon, rIghtCaptlon: DI. Caption]; 

DIP.FieldProps: TYPE = LONG POINTER TO DIP.FieldPropsRecord; 
DIP.FieldPropsRecord: TYPE = RECORD[ 

1 angu age : Mu Tt i N at i ona 1 . Langu age , 

length: CARDINAL, 

required: BOOL, 

skiplf: DIP.SkipIfChoiceType, 

stopOnSkip: BOOL, 

type: DIP.FieldChoiceType, 

• • • 1 5 

As in AddlextFrame, you specify want*Hand1e for those objects to which you 
want to add text. 
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Adding a Bitmap to a Graphics Frame 

A bitmap, as defined by its bitmapProps, can be added to a graphics frame. 

GI.AddBltmap: PROC[ 

h: GI. Handle, box: GI.Box, 

bitmapProps : GI . ReadonlyBi'tmapProps , 

f rameProps : GI . ReadonlyFrameProps , 

wantTopCapt1onHand1e , wantBottomCaptionHandle , 

wantLeftCaptlonHandle. wantRlghtCaptlonHandle: BOOLEAN ^ FALSE] 

RETURNS[ 

topCaption, bottomCaption, 

leftCaptlon, rIghtCaptlon : DI. Caption]; 

GI. BitmapProps: TYPE = LONG POINTER TO GI.BitmapPropsRec; 
BltmapPropsRec: TYPE = RECORD! 

opaque: BOOLEAN, 

xOffset, yOffset: LONG INTEGER. 

printFile: XString.ReaderBody, -nameof print file if desired 

displaySource: GI.BmDi splay, 

seal 1 ngProps : G I . B 1 tmapScal 1 ngProps , 

sparel: LONG CARDINAL]; 
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Bitmap Display and Scaling Props 

GI.BmDisplay: TYPE = RECORD [ - bitmap source is either internal 

SELECT type: * FROM (the bits are copied into the document) or a desktop file. 

internal => [bm: LONG POINTER TO GI.BitmapData] , 
file => [name: XString.ReaderBodyl , 
ENDCASEl; 

GI.BitmapData: TYPE = RECORD! 

signature: INTEGER Gl.bmSignature, -do not use any other value 
xScale: Interpress. Rational, 
yScale: Interpress. Rational , 

xDim: CARDINAL, yDim: CARDINAL, -# of bits wide and tall 

bp 1 : CARD I NAL , - Bits Per Line = ((xDIm +15)116)* 16 

pages: NSSegment.PageCount, 

bits: PACKED ARRAY [0..0) OF Environment. Byte ] ; 

GI.BitmapScalingProps: TYPE « RECORD! 
SELECT type: * FROM 
printerResolution => [resolution: CARDINAL], 
fixed => [ 

horizontalAlignment: {center, right, left}, 
vertical Alignment: {center, bottom, top}, 
scalingPercentage: CARDINAL [0..1024)], 
automatic => [shape: {similar, fillUp}], 
other => [ 

sparel: PACKED ARRAY [2. .15) OF [0..1], spare2: CARDINAL], 
ENDCASE]; 
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Adding an Image Frame to a Graphics Frame 

An image frame is defined by its ImageProps and its box within the frame. 
An image frame deals with Xerox' 9700 product and is beyond the scope of 
this class. 

GI.Addlmage: PROC[ 

h: GI. Handle, box: GI.Box, 

ImageProps: GI . Readonly ImageProps, 

f rameProps: GI . Readonly FrameProps , 

wantTopCaptlonHandle , wantBottomCaptlonHandle , 

wantLef tCaptlonHandle, wantRightCaptlonHandle: BOOLEAN FALSE] 

RETURNS[ 

topCapti'on, bottomCaptlon , 

leftCaption, rightCaptlon: DI. Caption]; 
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Adding Other Objects to a Graphics Frame 

other objects are defined by their Instance and box within the frame. One 
example of usage would be adding VP Charts to a graphics frame. 

GI.AddOther: PROC[ 

h: GI. Handle, box: GI.Box, Instance: DI. Instance]; 
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Constants and Defaults 

You can get "neutral" property values by specifying one of the following 
constants: 

GI.nuHBItmapProps: GI .BItmapPropsRec = [...]: 
GI.nu11BmD1splay: GI.BmDIsplay = [...]: 

GI.nu11BitmapSca1 ingProps: GI .BItmapScal ingProps = [ ]; 

GI.nullButtonProps: GI .ButtonPropsRec = [ ]; 

GI . nul ICurveProps : GI .CurvePropsRec = [ ]; 

GI . nul 1 EccentricCurveProps : GI . EccentricCurvePropsRec = [•••]; 
GI . null El 1 ipseProps : GI . El 1 ipsePropsRec = [...]: 

GI . nul 1 FrameProps: GI . FramePropsRec = [ ]; 

GI . nul 1 ImageProps : GI . ImagePropsRec = [•••]: 

GI.nullLineProps: GI . LinePropsRec = [ ]; 

GI . nul 1 RectangleProps : GI . RectanglePropsRec = [...]; 

Gl.nul ITextFrameProps: GI .TextFramePropsRec = [ ]; 

GI . nul ITriangl eProps : GI .TrianglePropsRec = [-.-]; 
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Adding Text to a Graphics Frame 

Text can be added to form fields, text frames, and captions of all frames (i.e. 
bitmap, image, text, button, and nested) and form fields. Note the return 
parameters for the following procedures: 

GI.StartGraphicsFrame: PROC[. . .] 
RETURNS[ 

gfh: GI. Handle, 
topCaption, bottomCaptlon, 
leftCaption, rIghtCaption: DI. Caption]; 

GI.AddFormField: PROC[...] 
RETURNS[ 

field: DI. Field. 
topCaption, bottomCaption, 
leftCaption, rightCaption: DI. Caption]; 

GI.AddTextFrame: PROC[...] 
RETURI\IS[ 

text : Text I ntepchangeDefs. Text, 
topCaption, bottomCaptlon, leftCaption, 
rightCaption: DI. Caption]; 
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Adding Text to a Graphics Frame (cont'd) 

Once you have a DocInterchangeDefs. Caption or DI. Field, you can use 
that Caption or Field as a DocInterchangeDefs. TextContainer and thus 
use the DocInterchangeDefs. Append* procedures to add various objects to 
it. 

DI. TextContainer: TYPE = RECORD[ 
var: SELECT type: ♦ FROM 
caption => [h: DI. Caption], 
doc => [h: DI.Doc]. 
field => [h: DI. Field], 
heading => [h: DI. Heading], 
footing => [h: DI. Footing], 
... 

ENDCASE]; 

When you have finished appending to the caption or field, call 
DocInterchangeDef s . ReleaseCaption or DI.ReleaseField to release any 
resources associated with the non-NiL handle. 

DI. ReleaseCaption: PROC[captionPtr: LONG POINTER TO DI. Caption]; 
DI.ReleaseField: PROC[f iel dPtr: LONG POINTER TO DI. Field]; 
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Adding Text to a Graphics Frame (cont'd) 

Once you have a TextlnterchangeDefs.Text (TID), you can add objects to 
that Text with calls to TextlnterchangeDef s.Append*ToText: 

TID.AppendCharToText: PROC[ 
to: TID. Text, 
char: XChar. Character, 
f ontProps:DIP. ReadonlyFontProps <- NIL, 
nToAppend: CARDINAL <- 1]; 

TID.AppendFieldToText: PROC[ 
to: TID. Text, 

fleldProps: DIP.ReadonlyFieldProps, 

fontProps: DIP. ReadonlyFontProps «- NIL] 
RETURNS[field: DI. Field]; 

TID. AppendNewParagraphToText: PROC[ 
to: TID. Text, 

paraProps: DIP. ReadonlyParaProps <- NIL, 
fontProps: DIP. ReadonlyFontProps «- NIL, 
nToAppend: CARDINAL *• 1]: 

TID.AppendTextToText: PROC[ 
to: TID. Text, 
text: XString . Reader , 
textEndContext : XString .Context, 
fontProps: DIP. ReadonlyFontProps «- NIL]; 
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Releasing Text 

When you've finished appending to Text, call 
TextlnterchangeDefs.ReleaseText to release any resources associated with 
the handle. 

TID.ReleaseText: PROC[textPtr: LONG POINTER TO TID.Text]: 
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Adding Text to a Button Program 

You can add text to the button program returned by the call to 
GraphlcsInterchangeDef s.StartButton. 

GI.AppendCharToButtonProgram: PROC[ 
to: GI.ButtonProgram. 
char: XChar. Character, 
fontProps: DIP. ReadonlyFontProps <- NIL, 
nToAppend: CARDINAL 1]; 

GI . AppendNewParag raphToButtonProg ram: PROC[ 
to: GI.ButtonProgram, 

paraProps: DIP. ReadonlyParaProps NIL, 
fontProps: DIP. ReadonlyFontProps NIL, 
nToAppend: CARDINAL 1]; 

GI . AppendTextToButtonProgram: PROC[ 
to: GI.ButtonProgram, 
text: XStrlng. Reader, 
textEndContext: XString .Context , 
fontProps: DIP. ReadonlyFontProps NIL]; 

GI.ButtonProgram: TYPE = LONG POINTER TO GI.ButtonProgramObject; 
GI.ButtonPrograniObject: TYPE; 
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Enumerating a Graphics Frame 

When enumerating a document with DocInterchangeDefs. Enumerate, you 
may want to look at the objects that are in the graphic frames of the 
document. You can enumerate those objects with a call to 
GraphicslnterchangeDefs . Enumerate. 

GI. Enumerate: PROC[ 
doc: DI.Doc, 

graph I'csContalner: DI . Instance, 
procs: GI . EnumProcs , 
ClientData: LONG POINTER NIL] 
RETURNS[dataSkipped: BOOLEAN]; 

The return parameter dataSklpped is not currently implemented and is 
always set to FALSE. 
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Enumerating a Graphics Frame Example 

Typically, you would call GI. Enumerate from the AnchoredFrameProc that 
was passed to did. Enumerate. 



AnchoredFrameProc: D I. AnchoredFrameProc = { 
< < dientData: LONG POINTER, type: DLAnchoredFrameType, 
anchoredFrame: DUn5tance,...>> 

enumProcs: GI.EnumProcsRecord [ - Some are defaulted to nil 

bitmapProc: MyBitmapProc, 

clusterProc: MyClusterProc, 

curveProc: MyCurveProc, 

elllpseProc: MyEllipseProc, 

lineProc: MyLineProc, 

pointProc: MyPolntProc, 

rectangleProc: MyRectangleProc, 

triangleProc: MyTriangleProc] ; 
myDoc: DID. Doc LOOPHOLE [cHentData]; 

ip'type = graphics THEN { 
[ ] G I. Enumerate [ 
doc: myDoc, 

graph icsContainer: anchoredFrame, 
procs: @enumProcs]; 

• . • 

}; 

• • • 
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EnumProcs 

GraphicsInterchangeDef s.EnumProcs are passed when enumeration is 
performed. A separate EnumProc is provided for each type of object that 
can appear in a graphics frame. If a procedure is defaulted to NIL, then 
nothing will happen when an object of the type covered by that procedure 
is encountered. The Enumerator always releases containers after calling 
each EnumProc. 

GI. EnumProcs: TYPE = LONG POINTER TO GI . EnumProcsRecord ; 
GI.EnumProcsRecord: TYPE = RECORD[ 

bItmapProc: GI .BItmapProc NIL, 

buttonProc: GI .ButtonProc ^ NIL, 

clusterProc: GI .01 usterProc NIL, 

curveProc: Gl.CurveProc NIL, 

ellipseProc: GI . Ell ipseProc ^ NIL. 

f ormFieldProc: GI . FormFiel dProc <r NIL, 

frameProc: GI.FrameProc <- NIL, 

ImageProc: GI . ImageProc <- NIL, 

lineProc: GI.LineProc <- NIL, 

otherProc: Gl.OtherProc *- NIL, 

pointProc: Gl.PointProc NIL, 

rectangleProc: GI .RectangleProc <- NIL, 

textFrameProc: GI .TextFrameProc NIL, 

triangleProc: GI .TriangleProc ^ NIL]; 
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LineProc, CurveProc, and PointProc 

These EnumProcs are similar in that they are all geometric objects. For each 
geometric object, a set of properties describing that object is passed into the 
appropriate procedure, box describes the position and size of the object 
within the frame. 

GI.LineProc: TYPE = PROC[ 
cHentData: LONG POINTER, 
box: GI.Box, 

1 ineProps : GI . ReadonlyLineProps] 
RETURNS[stop: BOOLEAN FALSE]; 

Gl.CurveProc: TYPE = PROC[ 
cllentData: LONG POINTER, 
box: GI.Box, 

curveProps: GI . ReadonlyCurveProps] 
RETURNS[stop: BOOLEAN ^ FALSE]; 

GI. PointProc: TYPE = PR0C[ 
CllentData: LONG POINTER, 
box: GI.Box, 

polntProps: GI . ReadonlyPolntProps] 
RETURNS[stop: BOOLEAN <- FALSE]; 
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EllipseProc, RectangleProc, and TriangleProc 

Each of these procedures represents a shape that can be shaded. 

GI.EllipseProc: TYPE = PROC[ 
clientData: LONG POINTER, 
box: GI.Box, 

el1 ipseProps : GI . ReadonlyE! 1 IpseProps] 
RETURNS[stop: BOOLEAN FALSE]: 

GI.RectangleProc: TYPE = PROC[ 
ClientData: LONG POINTER, 
box: GI.Box, 

rectangleProps: GI.ReadonlyRectangleProps] 
RETURNS[stop: BOOLEAN FALSE]; 

GI. TriangleProc: TYPE = PROC[ 
ClientData: LONG POINTER, 
box: GI.Box, 

trIangleProps : GI . ReadonlyTrlangleProps] 
RETURNS[stop: BOOLEAN FALSE]; 
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ButtonProc, ClusterProc, FrameProc 

These EnumProcs are similar in that they all deal with containers within 
graphics frame. 

GI.ButtonProc: TYPE = PROC[ 
clientData: LONG POINTER. 
graph1csConta1ner: DI. Instance, 
box: GI.Box, 

buttonProps : GI . ReadonlyButtonProps . 
f rameProps: GI . ReadonlyFrameProps, 
buttonProgram: GI .ButtonProgram] 
RETURNS[stop: BOOLEAN FALSE]; 

Gl.ClusterProc: TYPE = PROC[ 
cHentData: LONG POINTER, 
graphlcsContalner: DI. Instance, 
box: GI.Box] 

RETURNS[stop: BOOLEAN ^ FALSE]; 

GI. FrameProc: TYPE = PROC[ 
ClientData: LONG POINTER. 
graphlcsContalner: DI. Instance, 
box: GI.Box. 

f rameProps: GI. ReadonlyFrameProps, 
name, description: XStrIng . Reader, 
spareProps: LONG POINTER] 
RETURNS[stop: BOOLEAN <- FALSE]; 
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BitmapProc, FormFieldProc, and TextFrameProc 

These EnumProcs comprise the remaining procedures. 

GI.BitmapProc: TYPE = PROC[ 
cllentData: LONG POINTER, 
box: GI.Box, 

bitmapProps: GI . ReadonlyBI tmapProps . 
f rameProps : GI , ReadonlyFrameProps] 
RETURNS[stop: BOOLEAN <- FALSE]; 

GI.FormFieldProc: TYPE = PROC[ 
CllentData: LONG POINTER, 
box: GI.Box, 

f leldProps: DIP.ReadonlyFleldProps. 
f rameProps : GI . ReadonlyFrameProps , 
paraProps : DIP. ReadonlyParaProps , 
fontProps: DIP.ReadonlyFontProps , 

expandRlght, expandBottom: BOOL, content: DI. Field] 
RETURNS[stop: BOOLEAN <- FALSE]; 

GI. TextFrameProc: TYPE = PROC[ 
CllentData: LONG POINTER, 
box: GI.Box, 

f rameProps : GI . ReadonlyFrameProps. 
textF rameProps : GI . ReadonlyTextF rameProps , 
content: TextlnterchangeDef s . Text] 
RETURNS[stop: BOOLEAN FALSE]; 
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ImageProcs and OtherProcs 

Gl.ImageProc: TYPE = PROC[ 
cHentData: LONG POINTER, 
box: GI.Box, 

ImageProps : GI . ReadonlylmageProps , 
f rameProps : GI . ReadonlyFrameProps] 
RETURNS[stop: BOOLEAN ^ FALSE]; 

Gl.OtherProc: TYPE = PROC[ 
cllentData: LONG POINTER, 
box: GI.Box, 
instance: DI. Instance, 
obJectType: GI .OtherObjectType] 
RETURNS[stop: BOOLEAN FALSE]; 

G I. OtherObjectType: TYPE = MACHINE DEPENDENT { 
i n u s Frame ( 0 ) , -not implemented 

barchart, linechart, piechart, pies! ice, table, equation, 
f i rstAvai 1 abl e, 1 astAvai 1 abl e (255) } ; 
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Enumerating Text in Graphics Frames 

TextlnterchangeDefs (TID) allows you to enumerate text in a graphics 
frame. You supply three call-back procedures to handle fields, new 
paragraphs, and text. 

TID.EnumerateText: PROC[ 
text: TID. Text, 
procs: TID.TextEnumProcs , 
clientData: LONG POINTER ^ NIL] 
RETURNS[dataSk1pped: BOOLEAN]; 

TID.TextEnumProcs: TYPE = LONG POINTER TO TID.TextEnumProcsRecord; 

TID.TextEnumProcsRecord: TYPE = RECORD[ 
fieldProc: DI.FieldProc NIL, 
newParagraphProc: DI .NewParagraphProc ^ NIL, 
textProc: DI.TextProc <- NIL, 
tileProc: DI.TileProc <- NIL]; 



Day 4: GraphicslnterchangeDefs 



Advanced Viewpoint Programming Class - July, 1988 



4-46 



Enumerating a Button Program 

You can extract the contents of a Button program obtained by calling 
GraphlcsInterchangeDef s.EnumerateButtonProgram. 

GI . EnumerateButtonProgram: PROC[ 
buttonProgram: GI.ButtonProgram, 
p rocs : GI . ButtonProg ramEnumProcs , 
clientData: LONG POINTER ^ NIL] 
RETURNS[dataSk1pped: BOOLEAN]; 

GI .ButtonProg ramEnumProcs: TYPE = 

LONG POINTER TO GI .ButtonProg ramEnumProcsRecord ; 

GI.ButtonProgramEnumProcsRecord: TYPE = RECORD[ 
newParagraphProc: DI .NewParagraphProc *- NIL, 
textProc: DI.TextProc <- NIL]; 
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^ Retrieving Additional Anchored Frame Properties 

There are additional properties that you can store and retrieve from an 
anchored frame. 

GI.ExtraAnchoredFramePropsElements: TYPE = { 
name, description, spareProps}; 

GI.ExtraAnchoredFramePropsSel actions: TYPE = PACKED ARRAY 
GI. ExtraAnchoredFramePropsElements OF 
DIP . Bool eanFal seDef au 1 1 ; 

GI .GetExtraAnchoredFrameProps : PROC[ 
doc: DI.Doc. 

anchoredFrame: DI. Instance, 
spareProps: LONG POINTER NIL, 

zone: UNCOUNTED ZON E ] , - zone is for future use; return values are read-only 
RETURNS[name, description: XStrlng.ReaderBody]; 

GI .SetExtraAnchoredFrameProps: PR0C[ 
doc: DI.Doc, 

anchoredFrame: DI. Instance, 

name, description: XStrIng . Reader, 

spareProps: LONG POINTER ^ NIL, 

sel ections : GI . ExtraAnchoredFramePropsSelections] ; 
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The Big Example 

Here's how you would use GraphicsInterchangeDef s to copy graphics 
frames from one document to another. Basically you enumerate the objects 
in a graphics frame in the original document and append corresponding 
objects to a graphics frame in the new document. This example recognizes 
only graphics frames in the original document; everything else is ignored. 
Document and graphics handles are declared as global variables for 
simplicity. 

OPEN DI:DocInterchangeDefs, GI:6raphicsInterchangeDefs; 
original Doc, newDoc: DI.Doc; 
graph icsHandle: G I. Handle; 

CopyGraphicsFrames: PROC[sonieRef : NSFile. Reference] = { 
enumProcs: DI.EnumProcsRecord [anchoredPrameProc: Graph IcProc I ; 
newFile: NSFile. Handle NSFile. nullHandle; 
desktop: NSFile. Handle NSFile.OpenBy Reference I 

StarDesktop.GetCurrentDesktopFne[ ] ] ; 
originalDoc DI.Open[docFileRef : someRef ].doc; -should check for errors 
newDoc DI.StartCreation[].doc; 

[] ^ D I. Enumerate [text Container: [doc[h: originalDoc]], procs: ©enumProcs]; 
Dl.CloseldocPtr: ©originalDoc] ; 

[newFile,] DI.FinishCreation[@newDoc] ; -should check for errors 
" place new file on desktop 

NSFile. Move[file: newFile, destination: desktop]; 

StarDesktop.AddReferenceToDesktopl reference: NSFile. GetReference[newFile] ] ; 
NSFile. Close[newFile]; 

}; 

Graph icProc ; D I. AnchoredPrameProc = { 
graph icsEnumProcs: GI.EnumProcsRecord ^ [ 

clusterProc: MakeC luster . 

curveProc: MakeCurye, 

ellipseProc: MakeEllipse .. . . ] : 
graphicsInstance:DI. Instance; 
IF type # graphics THEN RETURN; 
graphicsHandle ^ G I. StartGraph1cs[ doc: newDoc]; 

[] GI. Enumerate [doc: originalDoc, graphicsContainer: anchoredPrame, 

procs : ©graph i csEnumProcs 1 ; 
graphicslnstance ^ GI.FinishGraph1cs[graph1csHandle]; 
[] DI.AppendAnchoredFrame[to: newDoc, type: graphics, 

anchoredPrameProps: anchoredPrameProps, content: graphicslnstance]; 

1; 
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MakeCluster: Gl.ClusterProc = { 
graph icsEnumProcs: GI.EnumProcsRecord [ 
clusterProc: MakeCluster . 
curveProc: MakeCurye, 
ellipseProc: MakeEllipse , . . , ] ; 
[] *■ G I. Enumerate [doc: originalDoc, graphlcsContainer: graphicsContainer, 
procs: ©graphicsEnumProcs] ; 

}; 

MakeCurye: GI, CurveProc = { 
GI.AddCurve[h: graphicsHandle, box: box, curveProps: curveProps]; 

}; 

MakeEHIpse : GI. EllipseProc = { 
GI.AddEll1pse[h: graphicsHandle, box: box, ellipseProps: ellipseProps] ; 

}; 
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Overview 

This section will help you produce code that will run faster and use less 
memory. We will discuss the Mesa machine and Pilot, and how you can use 
this knowledge to write more efficient code. 

• Page swapping is a major cause of poor program performance. If you 
reduce the number of swaps required for common operations, the 
performance benefits can be great. 

• Generally, most program computation occurs in small "hot" portions of 
code. We will discuss how to locate hot code and make it run as fast as 
possible. 

• The MDS is a scarce resource! By eliminating global variables, you can 
conserve the MDS and produce reentrant code. 

Keep in mind that the following suggestions all have trade offs (i.e. you 
might increase the speed of a program at the expense of code size). 
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Swapping 

Pilot swaps collections of pages called swap units; when anything contained 
inside a swap unit is needed in real memory, Pilot swaps in all of the pages 
of the swap unit. When Pilot needs to reclaim real memory, it swaps out 
individual pages. 

The Binder packages each module in a config into a single swap unit. Thus, 
Pilot swaps in an entire module even if only one procedure was accessed. 

Because of this behavior, you should limit intermodule references whenever 
possible. Shared code should be placed in a single "hot" module so that it 
will remain in real memory independent of the user's actions. Code specific 
to a user action can be placed in a separate module that is only swapped in 
when that action is invoked and swapped out when other actions occur. 
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Hot Code 

Many programs spend much of their processing time in a relatively small 
number of procedures. By locating these procedures and making them more 
efficient, you can often dramatically speed up your code. 

There are several performance tools that can be used to monitor the 
frequency in which procedures in a particular program are called. Using this 
information, we can isolate the hot code and spend more time increasing its 
speed. Similarly, the Lister utility allows you to list the machine code for 
procedures; thus, the code sizes for various algorithms can be compared. 
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Localizing Code 

A VP application may have several menu commands that are implemented 
by several different modules. If these commands are contained within the 
corresponding module (plug-ins), then when the application is opened, the 
system must take at least two page faults for each module. One page faults 
occurs for the global frame of each separate module and another for the 
actual code. 



— Foolmpi .mesa 



MenuOata. Createltem[ 
MenuOata.CreateItem[ 



.proc: FooOefs. Command 1. .. ]; 
.proc: FooOefs. CommandZ. .. ]; 



— FooImplA.mesa 



Commandl: PUBLIC MenuOata. MenuProc » {...}; 



—Foo Imp IB. mesa 



CommandZ: PUBLIC MenuOata. MenuProc - {•••}; 
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Localizing Code (cont'd) 

When you must use plug-in procedure values, you should place procedures 
with different functions in separate modules. In this fashion, you can reduce 
the amount of code that must be swapped in for a particular event. 

The idea here is to place code used for independent functions in relatively 
small modules to minimize the effect of swapping. Shared code and hot 
code should be placed in large modules that will, hopefully, remain resident 
in memory independent of the user's actions. 



—Biff Imp! .mesa 




— BIffHelpImpI .mesa 


module that uses plug-ins 


• 


Help: MenuProG = {...}; 


for commands: 


• 

« / 
♦ / 


<<other routines needed 


Help 


♦ / 
% / 


when Help 1s called>> 


Stop 


• / 
* / 




• / 
• / 

/ • 
/ • 

X • 




— BiffCommonlmpI .mesa 


/ • 

y • 
/ • 
/ • 

/ ^ 


— BlffStopImpl .mesa 




% 




Large module containing 
common code 




Stop: MenuProc = {...}; 
<<other routines needed 
when Stop is called>> 
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Direct Procedure Calls 



You should call directly to the source implementation, instead of calling 
other modules that eventually make the same call. This practice often occurs 
when you attempt to avoid modifying the client code after an 
implementation has been replaced. 

In the example below, FooClientlmpI should call FooPn'vOef s.RealGetNum 
directly. 

-- FooCIientlmpl.mesa 

mm: CARDINAL ^ FooDefs.GetNuml . 1 ; 
FoolmpLmesa 

gutted implementation (executable code is now In another procedure) 
GetNum: PUBLIC PROCl...] RETURNS [CARDINAL] = { 
RETURN! FooPrivOef S.Real GetNuml ...11; 

}; 

—fooPrivlmpl.mesa 

RealGetNuni: PUBLIC PR0C1...1 RETURNS(num: CARDINAL] = C 
< < get the number > > 
RETURN I numi; 

}; 
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Inline Procedures 

Using inline procedures correctly can potentially save two swaps per call; 
however, indiscriminate use of inlines can degrade compiler performance, 
cause tables to overflow, and generate vast amounts of code. Use inlines 
when you have: 

• a procedure that is defined in a PROGRAM module and called only once in 
that same module. This allows you to use procedures for program 
structure without the overhead of the procedure call. 

• a procedure that is small (no more than 6 byte codes) that has no local 
variables, no named return values and no side-effects. Such a procedure 
can be called an arbitrary number of times. 

• a procedure that no longer directly implements a function can be turned 
into an INLINE to efficiently redirect the client to the new implementation. 

During development, you should comment out the keyword "INLINE" until 
the program runs correctly, since an inline procedure cannot be debugged. 
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Minimizing Code 

Minimizing code is important since larger modules mean larger swap units, 
hence longer swapping times. Often a module is only a few words over a 
page boundary; by reducing the size of the code slightly, you can make the 
module fit. 

In addition to minimizing code, you should try reducing the size of Global 
Frames (GF) and the number of intermodule references (Links). Both of 
these structures must be swapped in, in addition to the code. You can used 
the Lister to show the size of the module's Global frame and the number of 
links. 



Day 5: Performance Issues 



Advanced Viewpoint Programming Class 



January, 1988 



5-11 



Package Code 

"Packaging" code places hot and cold code into separate swap units. The 
Packager is a post processor that lets you keep the logical structure of your 
modules, while dividing up the physical code. The packaging process itself is 
beyond the scope of this course. 
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Comment Unused Code 

Comment out unused procedures. Commenting not only reduces the 
amount of generated code, but also eliminates any links referenced only by 
the commented code. 

— commenting eliminates code, and the link forFooDefs 
« OldProc: PR0C1...1 RETURNS[...l « ( 

FooOef s.ProcOn1yCanedHere( . . . 1 ; 

• • * 

}; » 
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Eliminate Redundant Code 



Eliminate code that deals with situations that never occur or that is 
redundant. You should document your assumptions carefully to account for 
future changes. 

GetContext: PROCEDURE [body: Window. Handle] RETURNS [mydata: Defs.Oata] = { 
mydata Context .Find [context, body]; 
IF mydata « NIL THEN ERROR; -just in case, 
RETURN [ mydata 1; 

}; 

Entry point: 1, Frame size index: 0 

1245: SLD2 

1260: LLDO 

1246: LGB 26 

1250: LLD2 

1251: EFCB 26 

1253: PLDO 

1254: lOR 

1255: JNZ3 (1260) 

1256: KFCB 

1261: RET 
Instructions: 10, Bytes: 14 

VS. 

- the code should be fuily debugged 

GetContext: PROCEDURE [body: Window.Handle] RETURNS [mydata: Defs.Data] = { 
mydata Context. Find [context, body]; 

}; 

Entry point: 1, Frame size index: 0 



1245: 


SLDO 




1246: 


LGB 


26 


1250: 


LLDO 




1251: 


EFCB 


26 


1253: 


PLDB 


2 


1255: 


RET 





Instructions: 6. Bytes: 10 

The code to test the nil case is only needed before the program is fully 
debugged; thus, it can be removed. 
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Minimizing Code With INLINEs 

Let's take the GetContext procedure one step further and make it inline. 

Expert: MenuOata.MenuProc = { 
body: Window. Handle StarWIndowShell .6etBody( [window] 1 ; 
data: Oefs.Oata GetContext [ body ] ; 
data. level expert; 
}; 



GetContext: PROCEDURE [body: Window. Handle] RETURNS [Defs.Data] = INLINE { 
RETURN [ Context . F i nd [ context , body ] ] ; 
}; ~ generates no procedure body 

- with INLINEs, the call to GetContext generates this code 

1105:LG2 
1106:LLD2 
1107: EFC2 
1110:SLD4 
Instructions: 4. Bytes: 4 

VS. 

GetContext: PROCEDURE [body: Window. Handle] RETURNS [Defs.Data] = [ 
RETURN [Context. Find [context, body]]; 
}; — generates code for procedure body 

- without INLINEs, the same call to GetContext generates this code 

1106:LFC 1244 
1111: SLD4 
Instructions: 2. Bytes: 4 

So by using INLINEs in this situation, we have added two instructions, kept 
the code the same size, and elinfiinated a procedure call. 
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Pilot's Inline Interface 

In addition to making your own procedures INLINE, there is a separate Inline 
interface in Pilot. You should become aware of the procedures it contains 
since they are optimized by being in microcode. You should use the Inline 
interface when: 

Copying large amounts of data to or from VM. 
Inl ine. LongCOPY[. . .]; 

Performing LONG arithmetic. 
Inl Ine.LongMul t[ . , , ]; 
Inl 1ne. LongOi v[ . . . ] ; 

Operating on bits (i.e. shifts, rotates, etc.) 

Inline. BITSHIFT[. . 
Inline. BITROTATE[. . .]; 
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Reduce the Number of Links 

You should attempt to reduce the number of links (references to external 
procedures) that each module has. 

When initialization code references many external procedures that are not 
referenced by any other code, consider moving the init code to another 
module to minimize the size of the links array. 

When you split modules, try to place procedures that use similar sets of links 
together. For example, all the code that references the StarWindowSheil 
interface would be placed in a single module. 

Do not qualify procedures contained in the same modules (i.e. don't write 
Foo. Proc when in the module that implements Ppoc). 
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Optimize SELECtvstateme 




Avoid using select statements to perform simple mathematical mappings. 

Fruit: TYPE « {apple, orange, grape, tomato, cherry}; 
i: CARDINAL SELECT x FROM 

apple => 1, 

orange »> 2, 

grape => 3, 

tomato -> 4, 

ENDCASE => 5; 



1: CARDINAL ^ Fnjit.x.ORD + I; 

Note - your mathematical expression may not be very meaningful to other 
programmers; thus, you should always carefully document your 
assumptions. 



vs. 
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Special Mesa Machine Optimizations 

By understanding more about how the Mesa machine works, you can take 
advantage of special machine instructions. 

Loops should start with zero when possible because Mesa has a special 
machine instruction for testing [0. .n) where n is positive. Thus, IN [0. .4) 
generatesfewer bytes of code than IN [-2.. 2). 

The first sixteen words of a Mesa RECORD are the quickest to access; thus you 
should place the most frequently accessed data in the first sixteen words of 
all records. 

Access to fields in unpacked records requires less code than for packed 
records since the fields are word-aligned. In addition, packed records must 
be unpacked before accessing any of their fields. 
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Listing Assembly Language Code 

The Lister utility (documented in the Xerox User's Guide) allows you to 
display the assembly language code that is generated by the compiler. Thus, 
you can compare different algorithms and see which one produces less/ 
faster code. The Lister subsystem that you should use is "code." 

You can generate the assembly language code for a given ".bed" file by 
typing "lister cocle[f oo. bed]" into the Executive. The Lister will then 
generate a file called "f oo . ci " that contains the code. 
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Locating Hot Procedures 

As a programmer, you have some idea about what procedures will be used 
most frequently. To find out exactly which procedures in a module are 
invoked and how often, you can use the ProcList tool. The ProcList tool lets 
you "spy" on a particular module during some period of time (e.g. while 
playing a particular game). 

From the information below, we can determine that MyNotifyProc and 
GetContext are hot procedures. In addition, InRange and Word are called 
the same number of times, so they might be combined. 

Randomlmpl. ENTRY VECTOR 
Randomlmpl . Initialize 1 
Randomlmpl. InRange 246 
Randomlmpl .MAIN 1 
Randomlmpl .Word 246 
TipoMsg Imp 1. ENTRY VECTOR 
TipoMsglmpl .GetMessageHandle 2 
TipoTipImpl. ENTRY VECTOR 
TIpoTipImpl .MyNotifyProc 355 
TipoTipImpl .SetUpTipTable 1 
TipoTipImpl .Start 1 
TipoTipImpl .Stop 1 
TipoTipImpl .Trans 63 
TipoTool Imp! .AdvanceLines 188 
TipoTool Imp! .CheckUserAction 63 
TipoTool Imp! .DispTayAll Letters 2 
TipoTool Imp l.DisplayBox 254 
TipoTool Impl .DisplayColumn 66 
TipoTool ImploOisplayGrid 2 
Ti poToo 1 Imp 1 . 0 i sp 1 ay Letter 66 
TipoTool Impl .DisplayVertLines 2 
TipoTool Impl. ENTRY VECTOR 
TipoTool Impl .GenericProc 1 
TipoTool Impl .GetContext 424 
TipoTool Impl .GetRandomLetter 58 
TipoTool Impl .Initial izeGame 1 
TipoTool Impl. InvertPosition 154 
TipoTool Impl. MakeShell 1 
TipoTool Impl .MyRedlsplayProc 2 
TipoTool Impl .Pi ctureProc 1 
TipoTool Impl .PrintStats 1 
TipoTool Impl .Start 1 
TipoTool Impl .StringFromKey 66 
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Locating Hot Procedures (cont'd) 

The procedures on the previous slide were grouped logically into modules. 
The Packager would generate swap units that reflect the frequency that 
each procedure is called. You could package the code yourself using the 
data generated by ProcList. Only a few changes are needed to greatly 
reduce the number of intermodule calls. 

A major disadvantage of moving procedures is that your program begins to 
lose its readablity! 

— in1t code swapped out after use 
Randomlmpl. Initialize 1 
TipoTool Imp! .GenericProc 1 
TipoToolImpI .MakeShell 1 
TipoTool Imp! .Pi ctureProc 1 
TipoToolImpI .start 1 

TipoTool Imp l.PrintStats 1 
TipoToolImpI. Initial izeGame 1 
TipoTlpImpl .SetUpTipTable 1 

~ Hot code should stay resident 
Random Imp 1. I nRange 246 
Randomlmpl .Word 246 
TipoTlpImpl. MyNotifyProc 355 
T 1 poT ip Imp 1. Trans 63 
TipoToolImpI .AdvanceLines 188 
TipoTool Impl.GetContext 424 
TipoTool Impl.InvertPosition 154 
TipoToolImpI .CheckUserAct ion 63 
TipoTool Impl.DisplayBox 254 
TipoToolImpI .OisplayColumn 66 
TipoToolImpI .DisplayLetter 66 
TipoTool Impl .StringFromKey 66 
TipoToolImpI .GetRandomLetter 58 

— major display code called at beginning and end of program 
TipoMsglmpl .GetMessageHandle 2 

T i poToo 1 Imp l.DisplayA 11 Letters 2 
TipoTool Impl. DIsplayGHd 2 
TipoToolImpI .01 splay VertLines 2 
TipoToolImpI .My Redisplay Proc 2 
TipoTlpImpl. stop 1 
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Avoiding Recomputation 

You should avoid dereferencing multiple pointers whenever possible. As 
you begin using more complex data structures, it is better to define a local 
variable then to dereference similar expressions. OPEN statements will hide 
the problem but not make it go away. 

— generates more and slower code (the OPEN simply hides the dereferencing) 
OPEN a+.b+.c(dl+.elf ]; 

count count + 1; 
char charac; 
prop * property; 

Generates this code: 

a+.b+.c[d]+.e{f] .count a+.b+.cldl+.e[f] .count + 1; 
a+.b+.c[d] + .e(f ] .char charac; 
a+.b+.c(dl+.elf ] .prop * property; 

VS. 

— must allocate a local variable 

p: LONG POINTER TO MyType ^ @a+.b+.cld]+.e[f ] ; 
p. count p. count + 1; 
p. char *• charac; 
p. prop property; 
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Preallocate Data Nodes 

When you allocate nodes from the system heap, each node that you allocate 
may come from a different disk page. To avoid this, you should create a 
private heap from which to allocate nodes. This Is especially important for 
structures such as linked lists that may need to be searched. You must weigh 
the cost of creating a private heap vs. the cost of potential page faults in the 
system heap. 

You should consider using arrays rather than linked lists. Even though arrays 
have compute time deficiencies, you will avoid the fragmentation that 
occurs when using linked allocation. 
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Minimize Data 

• Data should be allocated from one big node rather than several small 
nodes to save on node overhead. Very large nodes can be allocated using 
the Pilot Space interface (i.e. arrays vs. linked nodes). 

• Minimize global frame size. There is currently a limit of 64k of global 
frame space for ail processes. ViewPoint software uses a great deal of this 
allocation already, so you should make every attempt to minimize your 
impact on this resource. 

• Minimizing local variables can result in smaller local frames, hence faster 
procedure calls. Remember that local frames are allocated from the MDS 
too; thus, recursive procedures should not have large local frames. 
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Reduce Global Data 

• You can allocate ail global variables associated with your application 
from a heap; this data can later be retrieved using procedures from the 
Context interface. Examples of this technique can be found in all of the 
exercises for this course. 

• Data that is associated with all instances of an application (atoms, heaps, 
etc.)/ can also be allocated from a heap. Thus, the only global variable 
that your application needs is a long pointer to this record. The 
disadvantage of allocating the data from a heap is that you must 
dereference a pointer to access it. 
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Global Data Example 

< < Waste of MDS> > 

AtomList: TYPE = {open, takeCopy, takeMove, canYouTake, props}; 
" Gtobal variables 

z: UNCOUNTED ZONE ^ BWSZone. Permanent (] ; 
atoms: ARRAY AtomList OF Atom. ATOM ^ ALL[Atom.nun 1 ; 
bigWrlter: XStrlng.WriterBody ^ XString.NewWriterBody{255, z]; 
name: XStrlng.ReaderBody * XStr1ng.FromSTRINGl"Name for menu"L]; 
count: CARDINAL * 0; 

Compiler. . . 

lines: 20, code: 75, links: 3, frame: 35, time: 28 
»»> uses 35 words of global frame! ««< 

< < Conserve MDS> > 

AtomList: TYPE = {open, takeCopy, takeMove, canYouTake, props}; 
Global s: TYPE = LONG POINTER TO GlobalData;. 
GlobalData: TYPE = RECORD [ 

z: UNCOUNTED ZONE, 

atoms: ARRAY AtomList OF Atom. ATOM, 

bigWriter: XString.WriterBody, 

name: XString.ReaderBody, 

count: CARDINAL]; 

~ Global variables 
g: Globals NIL; 

— Initialize 
Init: PROC » { 

z: UNCOUNTED ZONE ^ BWSZone. Permanent! I ; 

rb: XString.ReaderBody XString.FromSTRINGrt"Name for menu "LI; 

g ^ z.NEWlGlobalData ^ [ 
z: z, 

atoms: ALL [Atom. null ] , 
bigWriter: XString.NewWriterBody[255, z], 
name: XString.CopyToNewReaderBody[@rb, zj, 
count: Oil; 

}; 

Compiler ... / < 

lines: 34, code: 124, links'^ 4, jframe: 6, time: 30 

>» Provides sane data structures, but only uses 6 words. «< 
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XString Usage 

Creating and destroying XString.WriterBodys can be expensive. If you are 
using the WriterBody for formatting output, then it is better to allocate a 
single large WriterBody and reuse it. 

You should never use XString.FromSTRING for global strings; these are 
better allocated from a heap. In general, ail strings should be stored and 
accessed via XMessage. 
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Heaps 

Heaps are used for storing data for all or part of the duration of a program. 
Indiscriminate heap usage can result in unused heap pages, expansion or 
fragmentation of the heap. By examining the behavior of your program, 
you can make decisions that will minimize these undesirable effects. 

Growing a sequence is an expensive heap operation because of the time 
spent copying information and the need to allocate additional space for the 
new sequence. The cost of allocating the new sequence is the more serious 
problem since it may involve growing the heap and it creates a lot of unused 
heap space. If the heap is also used for other structures, then the heap 
mechanism may not be able to coalesce freed sequences. 

Too many heaps (distributed heaps) can cause problems as well. Since heaps 
are located in VM, they must be swapped into real memory before they can 
be used. You may end up swapping each time you make a reference to a 
different heap. 
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NSFiling 

Since NSFiling involves the disk, it is inherently slow. Because of this, you 
should minimize the number of calls to NSFile. When you must perform 
lengthy filing operations (i.e. remote file transfers), you may want to do so 
in the background. 



wp^r a LlOi 1 


MV^ 1 line 


ChangeAttributes (numeric) 


.224 


ChangeAttributes (string values) 


.245 


Create directory (size = 0) 


.761 


Create directory (size = 10) 


.987 


Create directory (size = 100) 


1.288 


Delete directory (size = 0) 


.538 


Delete directory (size = 10) 


.677 


Delete directory (size = 100) 


.940 


Create temp file (size s 0) 


.357 


Create temp file (size = 10) 


.450 


Create temp file (size = 100) 


.729 


Delete temp file (size = 0) 


.293 


Delete temp file (size = 10) 


.367 


Delete temp file (size = 100) 


.613 


Listing files (number s 10) 


.266 


Listing files (number = 50) 


1.251 



Some recent benchmark times for common NSFile operations 
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NSFiling (cont'd) 

Opening an NSFile can take between 22 and 500 milliseconds, depending on 
the size of the file. Since this takes so long, it is better to leave files open 
until they are no longer needed. Similarly, mapping a file to VM can take up 
to 300 milliseconds. Since mapping is so expensive, you may want to try to 
map all portions of a file that will be needed and let Pilot worry about 
managing the space. 

However, mapping a large file for an extended period of time will impact 
other applications. 
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Concurrency 

It would be nice to be able to retrieve a large folder from a server and still 
be able to edit some other file. However, the current implementation 
performs file copies in the foreground. You can obtain a significant 
perceived performance improvement by forking such operations when 
possible. 

There are some obstacles with concurrent filing operations. First, the 
Attention interface will only post messages from a foreground process. 
However, from a forked process, you must use the BackgroundProcess 
interface to post messages to the user. Second, ail filing requests within a 
session are executed consecutively, not concurrently. In order to have 
concurrent filing operations, you must establish a separate session for each 
file operation (discussed later). 
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BackgroundProcess 

The BackgroundProcess (bp) interface provides user feedback and control 
facilities to clients that want to run in a process other than the Notifier. A 
process registers itself by calling BackgroundProcess. ManageMe. ManageMe 
requires a call-back procedure to perform the actual work, and it is within 
this call-back that messages may be posted. If the call-back procedure is 
prepared to catch the ABORTED SIGNAL, then abortable should be set to 
TRUE. 

BP. ManageMe: ManageProc; 

BP.ManageProc: TYPE = PROCEDURE [ 
name: XStrIng .Reader, 
cal IBackProc: BP.Cal IBackProc, 
window: Window. Hand1 e ^ NIL, 
Icon: Cental nee. DataHandle ^ NIL, 
context: LONG POINTER <- NIL, 
abortable: BOOLEAN <- FALSE] 
RETURNS[final Status: BP. Final Status] ; 

BP.Cal IBackProc: TYPE = PROCEDURE [context: LONG POINTER] 
RE rURNS[final Status: BP. Final Status]; 

BP.FinalStatus: TYPE = MACHINE DEPENDENT {ImportantFailure(O) , 
failure, quietSuccess , success, aborted, firstFree, last(15)}; 
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Establishing Separate NSFile Sessions 

Most NSFile operations require a NSFile. Session haridle, which is normally 
defaulted. Within this default session, all file requests are handled 
consecutively. If you want to perform concurrent NSFile operations you 
must establish a separate session handle. You must first acquire an 
Auth.IdentityHandle by calling Atom.GetProp. By calling GetProp with 
atoms "CurrentUser" and "IdeplityHandle", you will receive as the 
Pai p . val ue the ^ijth . Identi tyHan4i e for the currently logged-in user. 

Atom.GetProp: PROCEDUREContc/, prop: Atom. ATOM] 
RETURNS[paip: Atom. Ref Pa/p] ; 

Atom. Ref Pair: TYPE = LOWG POINTER TO READONLY Atom. Pair; 

/ / 

Atom. Pair: TYPE ° RECORD[prop: Atom. ATOM, value: Atom. Ref Any]; 

Atom. Ref Any: /ypE = /oNG POINTER; 

/ / 

Once you have the ^\^tt^ . Identi tyHandl e, you can establish a new session by 
calling NSFlW. Logon. 

NSFile. Logon: PROCEDURE[ Identity: Auth. Identity] 
RETURNSCNiSFII/e. Session]: 
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Concurrency Example 



— CopyfilelmpLmesa 

DIRECTORY 
Atom, 

Attention, 
Auth, 

BackgroundProcess , 

CopyOefs, 

Courier, 

MenuOata, 

NSFIle, 

Process, 

Selection, 

StarOesktop, 

StarWindowShell , 

Window, 

XMessage 

XString; 

CopyFilelmpl: PROGRAM 

IMPORTS Atom, Attention, BackgroundProcess, Courier, CopyOefs, NSFile, Process, 
Selection, StarOesktop, StarWindowShell, XMessage, XString 

EXPORTS CopyOefs (OPEN Defs: CopyOefs; 



~ get reference to destination, if no dest selected, copy source to desktop 
Confirm: PUBLIC MenuOata. Menu Proc » { 
body: Window. Handle StarWindowShell .GetBody[ [window] J ; 
data: Defs. Data Def s.GetContext(body] ; 
data. dest GetSelectedFilel iOefs.FileProblem => 
{data. dest * StarOesktop.GetCurrentOesktopFilef 1 ; 
CONTINUE}]; 

Process . Detach [ FORK DoBackgroundCopy I data ] 1 ; 

}; 

" stores a reference to the selected file and prompts for dest 
Copy: PUBLIC MenuOata. MenuProc = { 

body: Window. Handle StarWindowShell .GetBody( [window] ] ; 

data: Defs. Data GetContext[body] ; 

mh: XMessage. Handle - Defs.GetHandlef] ; 

msg: XString.ReaderBody XMessage. Get [rah, Defs.keys.clickConf irm] ; 
data.source * Defs.GetSelectedFile[ iFileProblem *> GOTO Exit]; 
Attention. Post [©msg] ; 
EXITS 
Exit NULL; 

}; 
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— Call the CopyFUe procedure to copy the source file to the destination. Establish a separate session 

— for the copy so that other NSFile operations can occur concurrently. After the file is copied, 
ail handles are closed, the session is closed, and a message is printed 

DoBackgroundCopy: PROCEDURE [data: Oefs.Oata] » { 
" the call-back: proc for ManageMe must be internal 
CopyFUe: BackgroundProcess.CanBackProc » { 
good: XString.ReaderBody ^ XString.FromSTRING( "File Copied"L]; 
currentUser: Atom. ATOM Atom.MakeAtomf "CurrentUser"L] ; 
identltvHandle: Atom. ATOM Atom.MakeAtomf "Ident1tvHand1e"L] : 
identity; Auth. IdentitvHandle Atom.GetProp f 

currentUser , i dent 1 tyHand 1 e h . va 1 ue ; 
session: NSFHe. Session NSFi le.Logonf identity] : 
source: NSFile. Handle NSFi le.OpenSy Reference! 

reference: data.source, session: session]; 
dest: NSFile. Handle ^ NSFile.OpenByReference( 

reference: data. dest, session: session]; 
dummy: NSFile. Handle NSFile. Copy ( 

file: source, destination: dest, session: session 

INSFile. Error =*> [NSFile. Logoff (session: session]; GOTO Exit}]; 
NSFile.Close(dummyl; 

NSFile. Close I source]; Vr ■ 

NSFile. Close(dest]; 
NSFile.Loqofff session; session] : 
Attent i on . Post I @good ] ; 

RETURN [success]; \ 
EXITS Exit => C ^ . 

mh: XMessage. Handle = Def s.GetHandle[ ] ; 

bad: XString.ReaderBody XMessage. Get [mh, Defs.keys.notCopied] ; 

Attent i on . Post [ @bad ] ; < < close files > > ; 

RETURN(failure]}; 

}; 

Process .SetPri ori ty f Process . priori tyBackground ] ; 

[] ^ BackqroundProcess. ManageMe [name: @name. cal IBackProc: CopyFile]; 

}; 



- convert the selection to a file; if there is a problem print a message and 

raise the SIGNAL Defs.FHeProbiem 
GetSelectedFile: PUBLIC PROC 

RETURNS [ref: NSFile. Reference ^ NSFile. null Reference] = [ 
element; Select ion. Value Selection.Convert[ target: file]; 
refPtr: LONG POINTER TO NSFile. Reference. element. value; 
handle: NSFile.Handle ^ NSFi le. null Hand! er^ 

' ~rF^?Pt r"^mrTHrN"i: - - - 

mh: XMessage. Handle - Defs.GetHandlei ] ; 

msg: XString.ReaderBody * XMessage. Get (mh, Def s.keys.badFile] ; 

Attention. Post[@msg] ; ; 

SIGNAL Defs.FileProblem}; ^ 
ref refPtrt; 
Se lect ion. Free [ @e 1 ement ] ; 

)^*' ^ 
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Summary 

All of the techniques that we have discussed will improve the performance 
of your programs. However, in some cases the changes may not be 
noticeable because the time savings is in milliseconds. You may notice the 
change with larger programs or programs that perform a lot of swapping. 

Many of the methods discussed make your programs harder to read and 
debug. In general, you should strive to first make your program work 
correctly, and then to make it run faster. You must also consider that other 
programmers may have to support your program in the future, so 
readability is important. 
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Programming Lab Hints 



The Training Lab is located in room C401, next door. There are 20 machines available, so there should be 
one for everyone. The machines are already set up to contain all of the software you will need for the 
week. You will spend the afternoons completing one or more programming exercises. Before you start, 
there are a few things that you should know about the machines and the assignments: 

1) The afternoon labs are "Free Form". That is, you may come and go as you please, taking breaks and 
lunch as you wish. We do expect, however, that you do put some effort into working on the day's 
assignment. 

2) In order for the instructors to understand how well the Information is getting through, we would like 
each of you to show one of the instructors a running version of your assignment. (We may choose to 
test a few key things to see how robust your implementation actually is.) 

3) There is an information card on each keyboard assigning you a logon name and password as well as 
other information about your machine. You do not need to be logged in to work in XDE or VP, 
although you do need to be logged in to perform any operations over the net (e.g. Printing 
something). If you have your own logon name on the Xerox net, you may use it if you like. 

4) The lab machines have an established SearchPath of directories. These include a working directory 
(AVPWD), a BWS Interface directory (VPDefs), etc. To avoid problems, you should not alter this 
SearchPath. 

5) All code that you write will be contained in "template" modules; these modules will be specified in the 
exercise handouts. These templates contain "gutted" procedures with extensive comments. So after 
reading the exercise handout, you should locate the proper template module(s), read the comments, 
and then begin writing your code. You should not modify code in any other program modules; they 
only need to be compiled and bound. When compiling, you may recieve warnings indicating that a 
procedures or data type was declared but not used; this indicates that you did pot use some symbol 
that is in our solution. If the symbol is part of a user feedback function, you may wish to disregard the 
warning, but you should give careful attention to other symbols. 

After you get your template module to compile, you should do one of two things: 

1) edit the .config file associated with the program and change all instances of fooXXXimpI to 
fooXXXImplTemplate, or 

2) change the name (both internally and externally) of the fooXXXImplTemplate to fooXXXImpl. 
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6) You may (and should) choose your boot switches for Viewpoint depending on what your application is 
testing. If you do not rely on any VP applications (especially the Document Editor) then you should 
boot VP with the "ONdyXSes" switches; these can be set in the Command Central Option Sheet. The 
capital "N" means don't run any applications that are not on the Run-line of Command Central. One 
advantage of the "N" switch is that you don't need to specify a password when logging In, you simply 
select the Start command in the Logon Option Sheet. Another major advantage is that booting will 
take only about 4 minutes instead of about 12. Although, when you run the applications that call into 
DoclnterchangeDefs, GraphicslnterchangeDefs, etc, then you will need to run the Document Editor. (It 
is the Document Editor application that supplies the implementations for these Interfaces.) In this case 
you should boot VP with the "OdyVSeB" switches. 

7) XDE Documentation is located in the back of the room. There are copies of the Mesa Language 
Manual, Mesa Programmer's Manual, Pilot Programmer's Manual, XDE User's Guide, Viewpoint 
Programmer's Manual, and Services Programmer's Manual. You are encouraged to use these 
throughout the course, although they are to remain here for future students and classes. 

8) You may wish to personalize the User.cm on your workstation by changing the Hardcopy PrintedBy: 
option, or the default Brush, the Logon Name, etc. It is okay to do so, but you do not have to. 

9) At the end of each day, send a mail message to us mentioning what you liked or disliked about the 
day's work, any typos you noticed, bugs in the programs (ours not yours), or suggestions you may have. 
(We are constantly modifying the material based on students' suggestions.) The message may be as 
brief or lengthy as you like. We have found, though, that students who wait until Day 5 to summarize 
their thoughts in one message, tend to forget some of the thoughts that they had earlier in the week. 

10) Before you leave for an extended period of time (especially overnight), be sure to run some sort of 
DMT on the screen in order to protect them. There are many to choose from (e.g. DMT, BrushDMT, 
Poly, SpaceOut, KineticFractal, etc.). 

11) Most Importantly: ASK QUESTIONS! We are here to help you. Your lab instructors will be happy to 
answer any questions concerning the assignments or the lecture material, so don't be shy. Please report 
any bugs In the programs, or mistakes in the slides. 



E-Mail address: Mackay:OSBU North:Xerox 
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Lab Exercise: TIP 

^ Tipo 

Explanation of Game: The purpose of this game is to improve your typing skills and have fun (not 
necessarily in that order). The tool contains eight columns, with random letters at the bottom of each 
column. One of these letters will be highlighted. A black line in each column grows toward the bottom of 
the column. You must select the correct column and type the letter at the bottom of that column before 
the black line reaches the bottom. If you succeed, your score will increase, you will hear a high pitched 
beep, a new letter will be placed at the bottom of the column, and the blick line is reset to the top. If the 
line reaches the bottom before you type the letter, you will hear a low pitched beep, the black line will 
reset and a new letter will be placed at the bottom of the column. You get 50 chances altogether; the 
game will display your performance at the end of the game or when you select the Stop command. 

User Interface: You select the column that you want to type in by using the soft keys at the top of the 
keyboard (the ones marked CENTER, BOLD, ITALICS, UNDERLINE, SUPERSCRIPT, SUBSCRIPT, SMALLER, & 
DEFAULTS). The letter below the selected column will video invert. Once you've selected the column in this 
fashion, you type the corresponding letter on the keyboard. A low-pitched beep sounds if a black line 
reaches the bottom of the column before you type the correct letter. You can select one of three levels of 
difficulty: beginner, intermediate, or expert which alters the speed at which the line grows (i.e. there is less 
time to hit the appropriate key).. 
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Assignment: The tool uses several TIP features. First, Tipo uses its own TIP table to map the function keys to 
column numbers. This involves creating the table and associating it to the proper window. Second, the 
black lines are grown in a periodic notifier, with the amount of time between notifications dependent 
upon the level of difficulty. Finally, the NotifyProc that handles all user actions for the tool must recognize 
atoms and integers . Your assignment is to write all the TIP parts of TIpoTIPImplTempiate. The procedures 
you must modify are MyNotifyProc, Start, Stop, and SetUpTipTable. Hints are provided in the program 
module. 



Modules: Tipo.config 

TipoDefs.mesa 
TipoMsglmpl.mesa 
TipoTIPImplTemplate.mesa 
Ti poTool I m pi . m esa 
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Lab Solution: TIP 

^ Tipo 

FromTipoTiplmpl... 

— You'll have to recognize the "atom" and "int" variants from the input. The atom "advance" comes 
from the periodic notifier: if data.numLetters hasn't exceeded Def s .MaxLetters then call 
AdvanceLines, otherwise call Stop. If the atom "enter" is recognized, you'll set the input focus 
and the translator for this program, and push the table Tipo. TIP; if the atom is "exit," you 
must restore the old translator and pop Tipo. TIP. If the variant is int, that means one of the 
function keys was pressed. . .you have to call InvertPosition to dehighl ighted the current 

-- position, set data.currentPosition to the number passed in to MyNotifyProc, and call 

-- InvertPosition to highlight the new position. 

MyNotifyProc: PUBLIC TIP .Motif yProc =» { 
data: Oefs.Data *• Oefs.GetContext[window]; 

FOR input: TIP. Results *• results, input. next UNTIL input - NIL DO 
WITH z: input SELECT FROM 
atom "> 
SELECT z.a FROM 

advance => IF data.numLetters >" Def s. MaxLetters THEN Stop[window] 

ELSE Def s .AdvanceLines[data, window]; 
enter »> {TIP.SetInputFocus[w: window, takeslnput: FALSE]; 
data.oldTrans *• TIP.SetCharTranslator[ 
tabl e : TIPStar .GetTabl eCbl ackKeys] , 
new: data. translator]; 
TIPStar. PushTable[softKeys, table]}; 
exit =■> {[] TIP.SetCharTranslator[ 

table: TIPStar. GetTabl e[b1 ackKeys], 
new: data.oldTrans]; 
TIPStar . PopTabl e[sof tKeys , tab1 e]} ; 

ENOCASE; 

int "> {Defs.InvertPosition[data.currentPosition, window]; 
data.currentPosition «■ z.i; 

Defs.InvertPosition[data.currentPosition, window]}; 

ENDCASE; 
ENDLOOP; 

}; 
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~- Write the TIP table for the function keys at the top of the keyboard. The result for each key 

— should be an integer corresponding to that key's position. For example, the CENTER key should 

— have a result of 0, the BOLD key should have a result of 1, etc. These integers will be used by 

— the NotifyProc as data.currentPosition. Call TIP.CreateTable to set up the TIP table. 
-- Hint - there is no atom named LARGER. 

SetUpTlpTable: PUBLIC PROC [window: Window. Handle] > { 

fileName: XString.ReaderBody XString.FromSTRINGC"Tipo.TIP"L]; 
contents: XString.ReaderBody ^ XString . FromSTRING[" 
SELECT TRIGGER FROM 

CENTER Down »> 0; 

BOLD Down »> 1; 

ITALICS Down 2; 

UNDERLINE Down >> 3; 

SUPERSCRIPT Down =»> 4; 

SUBSCRIPT Down '> 5; 

SMALLER Down »> 6; 

DEFAULTS Down => 7; 
ENDCASE . . . 
"L]; 

table *- TIP.CreateTableCf ile: 8fileName, contents: Qcontents 

! TIP.InvalidTable => RESUME]; 
IF table > NIL THEN {--post a message--}; 

}; 

— This procedure is called by the Start MenuOata.MenuProc procedure. Set the translator variable 

~ passing window as the data argument. Create a periodic notifier and store it in the data object. 
-- Reset the counters data.numHits and data.numLetters to zero and star the game. 
-- The milliseconds field should depend on the value of data. level. 
Start: PUBLIC PROC [window: Window. Handle ] = { 

data: Defs.Data *■ Def s.GetContext[window] ; 

data. translator *- [proc: Trans, data: window]; 

data.numHits *- 0; 

data.numLetters «- 0; 

data. inProgress TRUE; 

data.periodlcNotify «■ TIP.CreatePeriod1cNot1fy[ 
window:window, 
results: OmyResults, 
fflllliSeconds: SELECT data. level FROM 

beginner ■> beginnerPeriod, 

intermediate ■> intermediatePeriod, 

ENDCASE -> expertPeriod]: 

}; 

~ Cancel the periodic notifier, stop the game, and Call PrintStats to print the 
-- statisitics of the player's performance. 
Stop: PUBLIC PROC[window: Window. Handle] « { 
data: Defs.Data «- Oefs.GetContext[window]; 

data.periodlcNotify *■ TIP. Cancel Per1od1cNotify[data.per1od1cNotify]; 
data. inProgress *■ FALSE; 
Defs.Pr1ntStats[window: window]; 

}; 
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Lab Exercise: Selection 

^ Checkers 

Explanation of Game: In this game for peasants and little kids, you move your pieces in the direction of 
your opponent, hoping to reach their side of the board, if one of your pieces reaches the other side, it 
becomes a "king* and can henceforth move freely around the board. You can jump an opponent's piece if 
it's adjacent to yours and the square immediately behind it is unoccupied. A king can jump in either 
direction; a regular piece can only jump in the direction that will advance it towards the opponent's side of 
the board. A player wins when he's jumped all of the opponent's pieces. 

User Interface: To move a checker, you select the desired checker and then select a new location for that 
checker When you select a new square, the checker is erased from the previous square and drawn in the 
new square. You select a checker by pointing at it with the mouse and clicking point down. Standard 
checker rules apply. The tool checks the legality of moves, although it doesn't keep track of who's turn it is. 
A jumped checker will disappear automatically. 
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Assignment: The tool uses a unique selection target type. When you click the mouse over a checker, that 
checker becomes the current selection. Your assignment is to write the selection manager part of 
CheckersSelectionlmplTempiate. This consists of the ConvertProc, ActOnProc, and ValueCopyMoveProc. In 
addition, you should write the procedure SelectChecker, which actually sets the selection. Hints are 
provided in the program module. 



Modules: Checkers.config 

CheckersBitmaplmpl.mesa 

CheckersDef s. mesa 

Checkerslmpl.mesa 

CheckersMsglmpl.mesa 

CheckersSel ecti on I m pi Tem pi ate . m esa 
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Lab Solution: Selection 

Checkers 

Called when user points over a square that contains a checker; 1t uses the call back procs 

ActOnSelectlon & ConvertSelection to handle marking and clearing as well as obtaining the 

— value and moving the checker. This procedure simply sets the selection. 
SelectChecker: PUBLIC PROCCsquare: Defs. Square] > { 

Selection.Set[ 
pointer: square, 
conversion: ConvertSelection, 
actOn: ActOnSelectlon]; 

}; 

Highlights the current selection and clears the old selection when a new one is made 

— (call -back from set). This proc should handle the following action: mark, unmark, & 
-- clear. Post a msg using Def s . kunknownAction for actions not handled by this proc. 
ActOnSelectlon: Selection. ActOnProc 

«[data: ManagerOata, action: Selection. Action] 
RETURNSCcl eared: BOOLEAN FALSE]» = { 

square: Defs. Square *■ NARROW[data, Defs. Square]; 
SELECT action FROM 
mark ■> IF "square. marked THEN 
{InvertChecker[square] ; 
square. marked «- TRUE}; 
unmark »> IF square. marked THEN 
{InvertChecker[square] ; 
square. marked *■ FALSE}; 
clear »> cleared TRUE; 
ENDCASE => { 
mh: XMessage. Handle > Defs.GetMessageHandle[]; 
msg: XString.ReaderBody <- XMessage. Get [mh, Defs. kunknownAction]; 
Attention . Post[0msg]} ; 

>l 
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— support conversion to the target type square; if successful, square will be returned. 
Enumeration is not supported. If the target is checker and there IS a checker on the 
square, then return the square, a pointer to the opsProcs, and, in the context arg, 

— the zone passed in. 

ConvertSel ectlon : Se 1 ec t i on . Con ve rt P roc 
«[data: ManagerData, target: TARGET, zone: UNCOUNTED ZONE, 
info: Selection. Conversionlnfo] RETURNS[value: Selection. Value]» ■ { 
square: Defs. Square *• NARROW[data, Defs. Square]; 
WITH i: info SELECT FROM 

query »> -only support conversion to checker no enumeration 
FOR c: CARDINAL IN [0. .LENGTHCi .query]) DO 
i .query[c] .difficulty 
IF ( i .query[c] .target » checker) AND (square. piece if none) THEN easy 
ELSE impossible 
ENDLOOP; 
convert => 

SELECT target FROM 
checker "> { ••ifachecl(erisselectedreturnap<^ntertoit 

IF square. piece = none THEN RETURN[Selection . nul IVal ue] ; 
RETURN[[value: square, ops: OopsProcs, context: LOOPHOLE[zone]]]} ; 
ENDCASE; 
enumeration >> NULL; 
ENDCASE; 
RETURN[Se1 action . nul 1 Val ue] ; 

}; 

— make a copy of the selected checker and delete the checker from the manager's data 

— structure, v. value is a Defs. Square so deleting checker consists of setting occupant 

— to none. Raise Selection .Error if op =■ copy since copy isn't be supported. Clear the 
selection and white out the piece in the old square. 

MoveChecker: Selection .Val ueCopyMoveProc 

«Cv: Selection. ValueHandle, op: Selection.CopyOrMove, data: LONG POINTER]» = { 
temp: Defs. Square *• NARROW[v. value, Defs. Square]; 
zone: UNCOUNTED ZONE ^ LOOPHOLE[v.context]; 
IF op > copy THEN ERROR Selection. Error[inval1dOperation]; 
V. value *- zone.NEW[Def s.SquareObject *■ tempt]; 
temp. piece *• none; 
Selection. C1ear[]; 

Display. Wh1te[temp. window, [temp. place, Defs.squareOims]]; 

>; 
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Concat 



Lab Exercise: DoclnterchangeDefs 



Explanation of Application: Concat takes a document or a folder of documents as a selection and creates a 
single document that is the concatenation of the input. 

User Interface: Select a VP document or a folder of VP documents and drop it on Concat. A property sheet 
will appear. You fill in the target file name and select Done. Concat will produce a new document with 
your specified name. 

Current restrictions in this application: anchored frames are not sent to the target document; instead, a 
text message is sent to the document as a placeholder. Also, headings and footings are not enumerated in 
the input documents and thus do not appear in the target document. 




Drop folder on Concat 
icon. Property sheet will 
come up. 



File Name 



Concat Sample 



+ 

t 



Assignment: In this assignment, you will write the code for generating a new document from the input. 
You will modify the module ConcatDoclmplTemplate by completing the procedures AppendFile, FieldProc, 
FirstNewParagraphProc. FirstPFCProc, InitEnumProcs, NewParagraphProc, and PFCProc. The input 
documents are enumerated with calls to OoclnterchangeDefs.Enumerate. You, as the programmer, will 
supply call-back procedures to handle each object that Enumerate finds. 

Modules: Concalconfig 

Concat Defs. mesa 
ConcatDoclmplTemplate.mesa 
Concatlmpl.mesa 
ConcatMsg I m pi . mesa 
ConcatPSheetl m pi .mesa 
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Lab Solution: DoclnterchangeDefs 

Concat 

Enumerate through the selected document and copy the contents to a target document, from 1s the 
source file to be enumerated. You must enumerate the contents of the froa file passed In. The 
cHentOata argument will be set to the context data for a11 enumerations. Close the fron doc 
-- before exiting. The call to DIO.StartCreatlon will occur In the FIrstPFCProc once the 

paragraph and PFC props have been obtained. 
AppendFlle: PUBLIC PROCCfrom :NSF11e. Handle, data: Oefs.Oata] - { 
ref: NSFile. Reference NSFne.GetReference[f 11e:f rom]; 
oldDoc: DoclnterchangeDefs. Doc; 
status : DocInterchangeOef s .OpenStatus ; 

[oldDoc, status] ♦■ DocInterchangeOef s.0pen[docF11eRef: ref]; 

IF status # ok THEN GOTO Exit; 

[] «- DocInterchangeOef s.Enumerate[ 

textContalner: [doc[h: oldDoc]], procs: Sdata.enumProcs, cHentOata: data]; 
DoclnterchangeDefs .CI ose[docPtr :8ol dOoc] ; 
EXITS Exit => { 

rb: XStrlng.ReaderBody *• Oefs.GetMessageCDefs.MessageKey.cantOpen.ORD]; 
Attention .Post[9rb]} ; 

}; 

Copy the field passed In to the text container spec-ffled by cllentOata. Since fields may contain 

— Information, enumerate the contents of the field. Before doing this, save the current 
data. container In a local variable, set data. container to be the container for the field, 

-- and then enumerate. Before exiting the procedure, restore the original data.coatalner. 
FieldProc: DoclnterchangeDefs. FleldProc > { 
data: Oefs.Oata *- LOOPHOLE[cl1entOata]; 

newFleld: DoclnterchangeDefs. Field <- DocInterchangeOef s.AppendF lei d[ 
to: data. container, fleldProps: fleldProps, fontProps: fontProps 
t DoclnterchangeDefs. Error >> GOTO bad]; 

— Now enumerate any Items within the field: save original container, put new 
container In data, then enumerate; afterwards, restore original container. 
origlnalTextContalner: DoclnterchangeDefs .TextContalner «• data. container; 
data. container [f1eld[h: newFleld]]; 
[] 4- DocInterchangeOef s.Enumerate[ 

textContalner: [f1eld[h: field]], procs: Qdata.enumProcs, cllentOata: data]; 
DocInterchange0efs.ReleaseF1eld[8newF1eld]; 
data. container «- origlnalTextContalner; 
EXITS bad -> NULL; 

}; 

— Append a new paragraph to the target doc. 
NewParagraphProc: DocInterchangeOef s .NewParagraphProc » { 

data: Oefs.Oata *• LOOPHOLE[cl lentOata]; 

[] *- DocInterchangeOef s.AppendNewParagraphCto: data. container, paraProps: paraProps 
I DoclnterchangeDefs. Error ■> { 

rb: XStrlng.ReaderBody <- Oefs.GetMessage[Defs.MessageKey.cantOpen.ORO]; 

Attention . Post[8rb] ; 

CONTINUE}]; 

>; 
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— For the 1st new paragraph of the first document to be concatenated, get Its properties only; 
I.e., don't append a new paragraph. Save these properties In the data object. The reason Is 

— that OID.StartCreatlon appends a new paragraph & a PFC automatically to a new doc, so you 
-- only want to copy the props to these default objects. 

FlrstNewParagraphProc: DocInterchangeDefs.NewParagraphProc » { 
data: Oefs.Data «- LOOPHOLE[cl ientOata]; 
numTabs: CARDINAL; 
data.propsRecord *• paraPropst; 

data.enumProcs.newParagraphProc *■ NewParagraphProc; 

-- Copy the array of tab stops Into data.propsRecord for temp storage 
numTabs *■ paraProps.tabStops. LENGTH; 

IF numTabs = 0 THEN RETURN; 

data.tabStopPtr Def s.z.NEW[Defs.TabSeq[numTabs]]; 
FOR 1: CARDINAL IN[0 .. numTabs) DO 

data.tabStopPtr[i] *■ data.propsRecord.tabStops[1]; 

ENOLOOP; 

data. propsRecord.tabStops. BASE *■ LOOPHOLE[data.tabStopPtr]; 
data. propsRecord.tabStops. LENGTH «- numTabs; 

}J 

Start doc creation using the saved paragraph properties and the PFC props passed into this proc. 

Set the PFC enumProc to PFCProc for any remaining PFC characters encountered and free any tabstop 

data that you allocated. 
FIrstPFCProc: DocInterchangeOefs. PFCProc - { 
data: Oefs.Data <- LOOPHOLECcl lentData]; 
startStatus : DocInterchangeDef s . StartCreationStatus ; 
data.enumProcs.pfcProc «* PFCProc; 

[doc: data. doc, status: startStatus] «- DocInterchangeDef s.StartCreation[ 

initialParaProps : Sdata.propsRecord, propsRecord from NewParagraphProc 

initial FontProps: fontProps, 

initialPageProps: pageProps]; 
IF StartStatus # ok THEN { 

rb: XString.ReaderBody *■ Defs.GetMessage[Defs.MessageKey.appendError.ORO]; 

Attention . Post[8rb]} ; 
data. container [docfh: data. doc]]; 
IF data. propsRecord.tabStops. LENGTH # 0 THEN 

Def s . z . FREE[Qdata .propsRecord . tabStops . BASE] ; 

}; 

— Append the PFC to the container specified by the c1 lentData argument 
PFCProc: DocInterchangeDef s, PFCProc ■ { 

data: Oefs.Data «- LOOPHOLE[cl lentData]; 
WITH z: data. container SELECT FROM 
doc ■> { 

[] *■ DocInterchangeDef s.AppendPFCCto: z.h, pageProps: pageProps, fontProps: fontProps 
! DocInterchangeDef s. Error «> GOTO bad]; 

}; 

ENDCASE; 
EXITS bad => { 

rb: XString.ReaderBody *■ Defs.GetMessage[Defs.MessageKey.appendError.ORD]; 
Attention . Post[9rb]} ; 

>; 
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Copyright (C) Xerox Corporation 1986. All rights reserved. 

This module provides facilities for appending several documents to a new 
document via DocInterchangeDef s . 



PROCEDURES 
AnchoredFrameProc: 
AppendF i le : 
ColumnBreakProc: 
FicldProc: 

Firs tNewParagraphProc : 
FirstPFCProc; 

In i tEnumProcs 
NowParagraphProc ; 
PageBrcakProc : 
PFCProc : 

SetTabStopDes crip tor: 
TextProc 



Enum Proc - appends text "{ <franie type> )" to new doc 

Public proc that opens <i enumerates a document 

Enum Proc - appends a column break 

Enum Proc - appends a field & enumerates field content 

Enum Proc - stores the paragraph props in the data object 

Enum Proc - starts document creation using saved para 
- props and PFC props passed in 

Public proc that initializes the call back procs in data 

Enum Proc - ^Ippends a new paragraph to tex tconta iner 

Enum Proc - appends a page break 

Enum Proc - appends a PFC to the tex tconta i ner 
Allocates stor&ge for tab stops 

Enum Proc - appends text to the new doc 



DtRECFORY 

Attention USING [Post], 

ConcatDefs USING [Data, GetMessage, MessageKey, fabSeq, z]. 

DocI nterchangeDef s USING [AnchoredFrameProc. AppendColumnBreak , AppendF ield. AppendNewParagraph , AppendPageBreak , AppendPKC, 

AppendText, Close, ColumnBreakProc, Doc, Enumerate, Error. Field. F'eidProc. MewParagraphProc , Open, OpenStatus. PageBreakProc , 

PFCProc, ReleaseField, StartCreation , StartCreationStatus , Tex tConta i ner . lextProc], 

NSFile USING [GetReference, Handle. Reference], 

UserTerminal USING [81 InkDisplay ] , 

XString USING [ReaderBody, unknon/nContext] ; 



ConcatDocIrapl : PROGRAM 

IMPORTS Attention, ConcatDefs, DocInterchangeDef s , NSFile. UserTerminal 
EXPORTS ConcatDefs [ OPEN Oefs: ConcatDefs; 

- Append msg in target doc saying what type of frame was encountered. 

- We do not implement anchored frames other than appending a msg 
AnchoredFrameProc: DocI nte rchangeDe f s . AnchoredF rameProc - f 

data: Oefs. Data *■ LOOPHOLE[c 1 ientData ] ; 
rb: XString. ReaderBody «- SELECT type FROM 

bitmap => Oefs . GetMessage[Defs .MessageKey . b i tmapFrame . ORD ] 
cuspButton => Def s . Ge tMessage[De f s .Mes sageKey . cuspButtoiiF r.5ni'- ORD | 
equation => Defs .GetMessage[Def s .MessageKey . equat ionFrame . OHij | . 
graphics => Defs .GetMessage[Def s .MessageKey .graph icsFrame ORD | , 
IMG ^> Defs. GetMessage[Defs .MessageKey . IMGFrame .ORD] , 
table => Defs .GetMessage[Defs .MessageKey . tableFrame .ORD ! 
text ^> Defs .GetMessage[Def s .MessageKey , textFrame .ORD] , 
ENDCASE => Defs .GetMessage[Def s .MessageKey . unknownFrame .ORD ] : 
DocInterchangeDefs .AppendTextfto: data . conta i ner , text: §rb. 

tex ttndContext : XStri ng . unknownContex t , fontProps: ancho ri on tjr(;p : 
I DocInterchangeDef s . Error -> f 

rb: XString. ReaderBody <- Oef s . GetMessage[Def s .MessageKey . appendError .ORD | ; 
Attention. Post[@rb] ; 
COI^TINUE}] ; 

}; 

- Enumerate through the selected document and copy the contents to a target 
document, from is the source file to be enumerated. You must 

-- enumerate the contents of the from file passed in. 
-- The c1 ientData argument will be set to the 

-- context data for all enumerations. Close the from doc before exiting 
-- The call to DID . StartCreat ion will occur in the FirstPFCProc once the 
-- paragraph and PFC props have been obtained. 

AppendFile: PUBLIC PROC[from: NSF i I e . Handl e , data: Defs. Data] = T 
openStatus ; DocInterchangeDef s .OpenStatus ; 
fromOoc: DocInterchangeDef s .Doc ; 

[fromDoc, openStatus] *• DocInterchangeDefs.Open[NSFile.GetReference[f lie: from]]; 

IF -openStatus = ok THEN {UserTermi na 1 . Bl i nkDi sp lay[ ] ; RETURN;}; 

[] «- DocInterchangeDef s . Enumerate[[doc[h : fromDoc]]. @data . enumProcs , data]; 

DocInterchangeDef s .CI ose[Sf roraDoc ] ; 

}; 

-- Copy the column break passed in to the text container specified by 

- - c I i e n t Da t a . 

ColumnBreakProc: DocInterchangeDe f s . Co 1 umnB reakProc ( 
data: D<fs.Data «- LOOPHOLE[cl ientData] ; 
WITH z: data. container SELECT FROM 

doc => [j «■ DocInterchangeOefs.AppendColumnBreak[ 
to:2.h, fontProps : fontProps 
' DocInterchangeDef s . Error '> [ 

rb: XString. ReaderBody «- Oef s .GetMessage[Oef s MessageKey .appendError . ORD ] : 
Attent ion . Post[@rb] ; 
CONTINUE}] ; 

ENDCASE; 



- Copy the field passed in to :ne text container spe-.'f'-ej C' eriuata. 
- Since fields may contain information, enumerate the -.^M.ei'.- o* the f;e^3 
; - Before doing this save the current data . conta i ne -n a -a'- -.ar aole ;e* 

tHW'^ ■■ data . container to be the container for ihe field, and the; enumer:ite. Before 

-- exiting the procedure, restore the original data . conta i ne- 
FieldProc: DocInterchangeOefs.FieldProc - j" 
data: Defs. Data -■ cl ientData; 
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newField: DoctnterchangeDefs. Field «- DocInterchangeDef s .AppeuilF le H( 
to: data. container, fieldProps: fieldProps, fontProps: foo. •■ jpi j : 
da ta . conta i lie r «- [field[h: newField]]; 

I] <- OocI nte rchangeOe fs . Enumerat6[da ta . conta i ner , 0data .enuniPro;-.s . data]: 
DocInterchangeDefs. Release Field[@newField]; 
^^^i da ta . conta i ner- •- [doc[h: data. doc]]; 

- For the 1st new paragraph of the first document to be concatenated, get its 

- properties only; i.e., don't append a new paragraph. Save these properties 

- in the data object. The reason is that 0 il) . StartC rea t ion appends a new 
— paragraph & a PFC automatically to a new doc. so you only want to copy 

the props to these default objects. 
F i rstNewParagraphProc : OocInterchangeDefs .NewParagraphProc - ( 
data: Defs.Data = clientData; 

data . enumProcs . newParagraphProc «- NewParagraphProc; 

data . propsReco rd paraPropsf; 

<< 

IF paraProps . tabStops ft NIL fUEN { 

newTabs: Def s . FabSeqPtr .^one . NEW( FabSeqf paraProps . tabStops . LENGTH]] ; 
FOR i: CARDINAL IN [0 ,. paraProps . tabStops . I tNG FH ) DO 

newrabs[il *- paraProps . tabStops[j | ; 

ENOLOOP; 
data . tabStopPtr *- Qnewlabs}: 

>> 

J; 

- start doc creation using the saved paragraph properties and the PFC props 

- passed into this proc. Set the PFC enumProc to PFCProc for any remaining 

PFC characters encountered and free any tabstop data that you allocated. 
F i rstPFCProc : Doc I nterchangeOef s . PFCP roc - { 

startStatus : DocI nte rchangeDef s . StartC rea t i onSta tus ; 
data; Defs.Data - clientData; 
data . enumProcs . pfcProc «- PFCProc; 

[doc: data. doc, status: startStatus] <- DocInterchangeDef s . StartCreation[ 

paginateOption : simple, 

i n it1al FontProps ; fontProps, 

initialParaProps: Sdata.propsRecord, 

initialPageProps: pageProps]; 
data .container <- [doc[h: data. doc]]; 
-- IF data.tabStopPtr # NIL THEN Def s . z . FREE[@data . tabStopPtr ] ; 
IF StartStatus » ok THEN DocInterchangeDef s .01 ose[@data .doc ) 

}: 

-- Initialize the Enumeration call-back procs in the data object 

- This proc is called when a file or folder is dropped on conca' 
InitEnumProcs: PUBLIC PROC[data: Defs.Data] - ( 

data . enumProcs <■ [ 

anchoredFrameProc : AnchoredFrameProc , 

'^ Mt, ....i.y ' columnBreakProc ; ColumnBreakProc, 

^Utf^ fieldProc: FieldProc. 

newParagraphProc : F i rs tNewl'aragraphProc , 

pageBreakProc ; PageBreakProc . 

pfcProc: FirstPFCProc , 

textProc: TextProc]; 

}; 

-- Append a new paragraph to the target doc. 
NewParagraphProc: Doc Inte rchangeDe f s . NewPa rag raphProc = | 
data: Defs.Data ^ clientData; 

OocInterchangeDefs .AppendNewParagraph[[doc[h: data. doc]], paraProps, fontProps]; 

): 

PageBreakProc: DocInterchangeDef s . PageBreakProc = { 
data: Defs.Data ^ LOOPHOLE[cl ientData] ; 
WITH z: data. container SELECT FROM 

doc => [] <- DocInterchangeDef s .AppendPageBreak[ 
to: z.h, fontProps: fontProps 
! DocInterchangeDefs .Error => ( 

rb: XString.ReaderBody - Def s . GetMessage[Def s .MessageKey . appendError .ORD] : 

Attention .Post [@rb]; 

CONTINUE}]; 

ENDCASE; 

}: 

Append the PFC to the container specified by the clientData argument 
-- * Can't default initialPageProps in S tartC reat i on if wan tHeadi ngHand! es or 

wantFootingHandles is TRUE. Steve Bartlett submitted AR SSG/ for this bug. 
-- * Can't enumerate headings or footings due to error in OocInterchangeDefs 
procedures EnunierateHeadPooting & EnumerateFl ow . Steve Bartlett submitted 
AR 8428 for this bug. 
PFCProc: Doclnte rchangeOefs . PFCProc = { 
data: Defs.Data = clientData; 

[] «- Docin terchangeOef s . AppendPFC[ to : data. doc pageProps; pag^i^rops. fontProps: fontPropsj: 



- Append the text passed in to the new text container 
TextProc: OocInterchangeDefs. TextProc = { 
data: Defs.Data - LOOPHOLE[cl ientData ] ; 
DocInterchangeDef s.AppendText[ 

to:data.container, text:text, textEndContext:textEndContex". 
fontProps : fontProps ! DocInterchangeDef s . Error -> > 

rb : XString.ReaderBody «- Def s .GetMessage[Def s .MessageKey appe^dErro ■.R'J] 
j^M*/ Attent ion . Post[@rb] ; 

CONTINUE)]; 

): 
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FMConverter 



Lab Exercise: TablelnterchangeDefs 



Explanation of Application: The FM Converter converts Viewpoint tables to "Static" tables and vice-versa. 

User Interface: Select a VP document and drop it on the FM Converter. For each table in the document, the 
FM Converter will produce a separate Static file. The converter will ignore ail other objects in the 
document. To convert back to a document from a Static file, select the Static file and drop it on the FM 
Converter. A new document containing the table will be produced and placed on the desktop. The Static 
file produced is read-only. 

Assignment: In this assignment, you will write the code for a table converter. One table format will be the 
Viewpoint document table, and the other will be a special table format called "Static." Static is a simple 
table implementation that has a small subset of the VP table properties. 

The Static icon is a separate application that implements its own file type. When you open a Static icon, the 
application draws the table represented by the data stored in the file. The data consists of the number of 
rows (including the header row), the number of columns, and fixed-sized blocks of text that represent 
table entries. 



Name 


Age 


Bill 


18 


Sally 


15 



2 


Name 


Age 


Bill 


18 


Sally 


15 



Number of columns 
Number of rows (including header) 

A Static table & the data file representing it 



When converting from a VP table to a Static table, the FM Converter uses OoclnterchangeDefs to 
enumerate the document in its quest for tables. For each one, it uses TablelnterchangeDefs to take the 
table information, create a Static file, and store the table information in that file. 

When converting from a Static table to a VP table, the FM Converter uses OoclnterchangeDefs to create a 
new document, and then uses TablelnterchangeDefs to create a VP table using the information from the 
Static file. 
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Assignment: 

Part 1: You have to implement procedures in FMConverterimplATemplate that deal with enumerating the 
VP table information and storing it into the Static file. The procedures are ConvertToFM, MyColumnProc, 
MyRowProc, MyTableProc, and TableProc. The procedures CreateDesktopFile, WriteReader, and 
WriteRowCol be handy for handling I/O and file creation. 

Part 2: You have to implement procedures in FMConverterlmplBTemplate that deal with extracting the 
table information from the Static file and creating a VP table in a new document; this new table should 
have the same content as the Static table. The procedures to implement are ConvertToDoc and 
SetProperties. You will find the I/O procedures AttachStream, GetCols, GetRows and GetReaderBody 
helpful. 



Modules: FM Converter, config 

FMConverterDefs.mesa 

FMConverterlmpl.mesa 

FMCon verterMsg I m pi . m esa 

FMConverterTablelmplATemplate.mesa 

FMConverterTablelmplBTemplate.mesa 

Static 




Blank 

Docunri 

ent 



Static file icon 



FM Converter 
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Lab Solution: TableinterchangeDefs 

^ FM Converter 

— FMConverterTab1eImp1A.mesa 

Copyright (C) Xerox Corporation 1986. All rights reserved. 

DIRECTORY 
OocInterchangeDefs USING [ 

AnchoredFrameProc, Close, Ooc, Enumerate, EnufflProcsRecord, Open, TextProc], 
Environment USING [Block, Byte], 

FMConverterOefs USING [FMFIleType, GetMessage, MessageKey, TextSIze, z], 
NSF11e USING [Attribute, Create, Error, GetReference, Handle, nullHandle, OpenByReference], 
NSFileStream USING [Create], 

StarOestctop USING [AddReferenceToDesktop, GetCurrentDesktopFHe], 

Stream USING [Block, Delete, Handle, PutBlock, PutWord], 

TableinterchangeDefs USING [ColumnsProc, EnumerateTable, EnumProcsRec, RowProc, TableProc], 
TextlnterchangeDef s USING [EnumerateText, Text, TextEnumProcsRecord], 
XChar USING [Character], 
XCharSetO USING [Make], 

XString USING [AppendChar, AppendReader, Insuf f IcientRoom, NSStrlngFromReader, 
Reader, ReaderBody, WriterBody, WrIterBodyFromBlock]; 

FMConverterTablelmplA: PROGRAM 

IMPORTS OocInterchangeDefs, FMConverterOefs, NSFHe, NSFileStream, StarOesktop, Stream, 
TableinterchangeDefs, TextlnterchangeDef s, XCharSetO, XString 

EXPORTS FMConverterOefs » { 

— Call-back procs for table enumeration. They will be called in the following order: 

— My TableProc, MyColumnProc, & MyRowProc once for each row of the table. 
tableProcs: TableinterchangeDefs. EnumProcsRec «- [ 

tableProc: MyTableProc, columnsProc: MyColumnProc, rowProc: MyRowProc]; 

Enumerate through the document specified by handle. For each 

— table encountered, invoke the call -back procedure TableProc. 
Conv«rtToFII: PUBLIC PROC [handle: NSF lie. Handle] - { 

docProcs: OocInterchangeDefs. EnumProcsRecord *- [anchoredFrameProc: TableProc]; 
doc: OocInterchangeDefs.DOC *• OocInterchangeDefs. Open[ 

docFileRef : NSFile.GetReference[handle]].doc; 
[] *• OocInterchangeDefs. Enumerate[textContainer: [doc[h: doc]], procs: SdocProcs]; 
DocInterchangeOef s .C1 ose[8doc] ; 

}; 
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-- Create Static file of size "byteSize" and place it on the desktop. 
" You can attach a stream to this file in order to write it 
CreateOosktopFile: PROCCbyteSIze: LONG CARDINAL] 

RETURNSChandle: NSFile. Handle *■ NSFi1e.nu11Hand1e] > { 
fileName; XString.ReaderBody *■ FMConverterOefs.GetMessageC 

FMConverterDef s.MessageKey.fmStaticName.ORD]; 
desktopHandle: NSFile. Handle «- NSFi1e.0penByReference[Star0esktop.GetCurrent0esktopFi 1e[]] ; 
attributes: ARRAY [0..3) OF NSFile. Attribute *■ [ 

[name[XString.NSStringFroniReader[r: 8fileName, z: FMConverterOef s.z]]], 
[sizeInBytes[byteSize]], 
[ ty peC FMCon ve rte rOef s.FMFileType]]]; 
handle ♦■ NSFile. Create[di rectory : desktopHandle, attributes: DESCRIPTOR[attributes]] ; 
StarOesktop.AddReferenceToOesktop[ reference: NSFile.GetReference[handle], pi ace: [0,0]]; 

>; 

Use this procedure to obtain the header information. When it is called, 
each header should be appended to the stream passed in as clientOata. 
MyColunnProc: TablelnterchangeOef s.ColumnsProc > { 

stream: LONG POINTER TO Stream. Handle *■ LOOPHOLECclientData]; 

text : TextlnterchangeOef s . Text; 

enumProc: TextlnterchangeOef s.TextEnumProcsRecord <- [textProc: TextEnumProc]; 
FOR i: CARDINAL IN [0. .columns. length) 00 

— extract the text from the specified column by calling the supplied 
proc and then enumerating the text object passed back. 

WITH x: col umns[i].headerEntryRec. content SELECT FROM 
read >> {text *• x.obtainTextProc[x.obtainTextData]; 
[] TextlnterchangeOef s .EnumerateText[ 
text: text, procs: QenumProc, clientOata: stream]}; 

ENDCASE; 
ENDLOOP: 

}; 

This proc is called once for each row of the table. The content of each 

element should be appended to the stream passed in as clientOata. 
MyRmProc: TablelnterchangeOef s.RowProc > { 

stream: LONG POINTER TO Stream. Handle *■ L00PH0LE[c11entData]; 
text: TextlnterchangeOef s. Text; 

enumProc: TextlnterchangeOef S.TextEnumProcsRecord <- [textProc: TextEnumProc]; 
FOR 1: CARDINAL IN [0. .content. length) 00 

— extract the text from the specified row by calling the supplied proc 
and then enumerating the text object passed back. 

WITH x: content[i]. content SELECT FROM 

read »> {text x.obta1nTextProc[x.obtainText0ata]; 
[] *- TextInterchangeOefs.EnumerateText[ 
text: text, procs: OenumProc, clientOata: stream]}; 

ENDCASE; 
ENDLOOP; 

}5 
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make private copy of text and pass the text back by assigning It to 

the reader body that cHentdata points to 
TextEnuaProc: OocInterchangeOefs.TextProc « { 

stream: LONG POINTER TO Stream. Handle *■ cllentData; 
Wr1teReader[text, streamt]; }; 

— The number of rows and columns are passed Into this proc. Use this Information to allocate a file 

— of the proper size where sIzelnBytes = ((numCols ♦ (numRows + 1) • text length) + 4. 

-- Write the number of rows and columns to the stream. The FM application treats headers the same 

— as any other row; this explains the + 1 in the calculation. The + 4 reflects the number of 
-- bytes required to store the 2 CAROINALs row and col. 

— CllentData Is a LONG POINTER TO Stream. Handle and It is this stream that we attach to the newly 

— created file. The other call-back procs will then write information to the same stream. 
MylableProc: TablelnterchangeDefs.TableProc - { 

stream: LONG POINTER TO Stream. Handle *■ L00PH0LE[c11entData]; 
fileSize: LONG CARDINAL *■ props. numberOf Columns ♦ 

(props .numberOf Rows + 1) ♦ FMConverterOefs.TextSize + 4; 
handle: NSFile. Handle «- CreateOesktopF11e[f ileSIze]; 
streamt <- NSF11eStream.Create[handle]; 

Wr1teRowCol[rows: props. numberOf Rows + 1, co1s: props. numberOf Columns, stream: streamt]; 

>; 



~ This procedure Is called once for each table encounted In the doc. It should enumerate through 

— the table and pass a pointer to a NIL stream as the cllentData argument handle. The call -back 

— procs can then attach this stream to a file and use it to append Information. 
~ Delete the stream before returning from this procedure. 

TableProc: OocInterchangeOef s.AnchoredFrameProc « { 
stream: Stream. Handle *• NIL; 
IF type # table THEN RETURN[]; 

TablelnterchangeDef s .EnumerateTableCtable: content, procs: 8tab1eProcs, cllentData: Qstream]; 
Stream. Oelete[streaml NSFile. Error «> CONTINUE]; 

}; 

— Pad or truncate the reader so that it Is Defs.TextSize bytes in length. 
" Write these characters to the Static file. 

WrIteReader: PROC[r: XString. Reader, stream: Stream. Handle] > { 

buffer: PACKED ARRAY [0. .FMConverterDefs.TextSIze) OF Environment .Byte; 
block: Environment. Block «- [Obuffer, 0, FMConverterDefs.TextSIze]; 
wb: XString. WriterBody *■ XString. Wr1terBodyFromB1ock[b1ock: block, inUse: 0]; 
space: XChar. Character «- XCharSetO.MakeCcode: space]; 

XString. AppendReader[ to: 8wb, from: r 1 XString. In$uff1c1entRoom RESUME]; 
DO blank out rest of writer 

XString. AppendChar[ to: Swb, c: space 1 XString. InsufficientRoom »> EXIT]; 

ENDLOOP; 

Stream. PutBlock[sH: stream, block: block]; 

>; 



-- Write the number of rows and columns to the Static file. 
WrlteRowCol : PROC[rows, cols: NATURAL, stream: St ream. Handle] 

Stream. PutWord [sH: stream, word: rows]; 

Stream. PutWord [sH: stream, word: cols]; 

>; 

>... 
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-- FMConverterTablelmplB.mesa 

Copyright (C) Xerox Corporation 1986. All rights reserved. 

DIRECTORY 

DocInterchangeOefs USING [AppendAnchoredFrame, CheckAbortProc, Ooc, FInlshCreatlon, StartCreatlon] , 
DocInterchangePropsOef s USING [FramePropsRecord], 
FMCbnverterOefs USING [TextSIze, z], 

NSFIle USING [Close, GetReference, Handle, Move, OpenByReference], 

NSFIleStream USING [Create], 

StarOesktop USING [AddReferenceToOesktop, GetCurrentDesktopFlle], 
Stream USING [GetWord, Handle], 

TablelnterchangeOef s USING [AppendRow, Columnlnfo, ColumnlnfoSeq, FilllnTextProc, FInlshTable, 

Handle, StartTable, TablePropsRec], 
TextlnterchangeOefs USING [AppendTextToText], 

XStnng USING [ 

AppendStream, NewWrlterBody, Reader, ReaderBody, ReaderFromWrlter, unknownContext, WrlterBody] ; 

FMConverterTablelmplB: PROGRAM 

IMPORTS DocInterchangeOefs, FMConverterDef s, NSF11e, NSFIleStream, StarOesktop, Stream, 
TablelnterchangeDefs, TextlnterchangeOefs, XStrlng EXPORTS FMConverterOefs > { 

OPEN Defs: FMConverterOefs, 01: DocInterchangeOefs, TI: TablelnterchangeDefs; 

— Table CONSTANTS and TYPEs 
marglnlnPlxels: CARDINAL » 35; 
mIcasPerPixel : CARDINAL = 9; 
tableWldth: CARDINAL = 3200; — micas 
tableHelght: CARDINAL > 3200; — micas 
rowMargin: CARDINAL = 100; — micas 

headerMargln: CARDINAL = marglnlnPlxels * mIcasPerPlxel ; 

RbArray: TYPE « RECORD[a: SEQUENCE max: CARDINAL OF XStrlng. ReaderBody]; 

RbArrayPtr: TYPE = LONG POINTER TO RbArray; 

Open a stream on the specified file. 
AttachStreaa: PR0C[f11e: NSFIle. Handle] RETURNS[stream: St ream. Handle] - { 
stream «• NSFIleStream. Create[f lie]; 

}; 
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Create a document with DocInterchangeOef s . Allocate the sequences that'll hold the information. 
Read the # rows & columns from the data file to determine the size of the table. Set up the table 

— and table frame properties. Read the header data from the data file. Use TablelnterchangeOefs to 
-- start the creation of a table. Read the data row by row into the table. Append the table 

— (anchored frame) to the document. Finish the document and place it on the desktop. Release 

— the handles to the new document and the data file. 
ConvertToOoc: PUBLIC PROC [handle: NSF He. Handle] » { 

tableHandle: TI. Handle; 

docFile: NSFHe. Handle; — the file to be created 

doc: OocInterchangeOefs.DOC *■ DocInterchangeOef s.StartCreation[]. doc; 

tableProps: TI .TablePropsRec; 

docFrameProps: OocInterchangePropsDef s.FramePropsRecord; 

— Allocate seqs for column, header, and row info 
stream: Stream. Handle *■ AttachStream[handle]; 

rows: NATURAL *■ GetRows[stream] - 1; -- the headers counted as a row 
cols: NATURAL*- GetCols[stream]; 

columnlnfo: TI .Columnlnfo «- Defs.z.NEWCTI.ColumnlnfoSeqCcols]]; 
headerRBs: RbArrayPtr *■ Defs.z.NEW[RbArray[cols]]; 
rowRBs; RbArrayPtr *■ Oefs.z.NEW[RbArray[co1s]]; 

[tableProps, docFrameProps] «- SetProperties[rows, cols, tableWidth, tableHeight]; 

— Fill in seq of column info 
FOR 1: CARDINAL IN [O..cols) DO 

headerRBs[l] *• GetReaderBody[stream, Defs.z]; 

co1umnInfo[i] ^ [ — all values except content and width taken from the null constant 
headerEntryRec: [ 

subHeaders: NIL, line: [solid, w2], singleLineHint : FALSE, sparel: 0, 
content: [write[f illlnTextProc: WriteText, clientData: 8headerRBs[i]]]], 

name: NIL, 

description: NIL, 

divided: FALSE, 

subcolumns: 0, 

repeating: FALSE, 

subcolumnlnfo: NIL, 

alignment: center, 

tabOffset: 0, 

width: tableWidth, 

leftMargin: 0, 

rightMargln: 0, 

type: any, 

required: FALSE, 

language: USEnglish, 

format: NIL, 

stopOnSkip: FALSE, 

range: NIL, 

length: 0, 

skipText: NIL, 

skipChoice: empty, 

finin: NIL, 

fillinRuns: NIL, 

line: [solid, w2], 

sortKeys: NIL, 

sparel: 0]; 
ENDLOOP; 
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— Create a table w/ appropriate props & column info 

tableHandle *• TI.StartTab1e[doc: doc, props: QtableProps, c: columnlnfo]; 
tableHandle. rc.topMargin *- tableHandle. rc.bottomMarg In «- rowMargin; 

— Read table entries from file & store 'em in row sequence 
THROUGH [O..rows) DO 

FOR j: CARDINAL IN [O..cols) DO 

rowRBs[J] «- GetReaderBody[stream, Defs.z]; 
tableHandle. rc[J] [ 
subRows: NIL, 
singleLineHint: FALSE, 
sparel: 0, 

content: [v»rite[f ill InTextProc: WriteText, clientData: 9rowRBs[j]]]]; 
ENDLOOP; 

TI .AppendRow[h: tableHandle, rc: tableHandle. rc]; 
ENDLOOP ; 

-- Finish table. Append table to document 
[] *- OocInterchangeDefs.AppendAnchoredFrame[ 

to: doc, type: table, anchoredFrameProps: QdocFrameProps, 

content: TI.FinishTable[ tableHandle] .table]; 

— Finish document and place it on the desktop 

[docFile,,] DocInterchangeDef s . FinishCreation[docPtr: @doc, checkAbortProc: DummyAbortProc]; 
NSFile.Move[f ile: docFile, destination: NSFile.OpenByReference[ 

StarDesktop.GetCurrentOesktopFile[]]]; 
StarDesktop.AddReferenceToDesktop[ reference: NSFile.GetReferenceCdocFile], place: [0,0]]; 
NSFile.CloseCdocFile]; 

>; 

need dummy to avoid control fault, found 3/10/87 
OuHiyAbortProc: DocInterchangeDef s. CheckAbortProc » {RETURN[FALSE]}; 

Help procedure to get the row and column info from the Static file 
GetCols: PROCCstream: Stream. Handle] RETURNSCcols: NATURAL] - { 
cols *- LOOPHOLE[Stream.GetWord [sH: stream]]; 

>; 

Help procedure to get the row and column info from the Static file 
GotRows: PROCCstream: St ream. Handle] RETURNSC rows : NATURAL] > { 
rows *- LOOPHOLE[Stream.GetWord [sH: stream]]; 

}; 

— Retrieve Defs.TextSize bytes from the Static file and return the ReaderBody generated from them. 
GetReadorBody: PROCCstream: St ream. Handle, zone: UNCOUNTED ZONE] RETURNSC rb: XSt ring. ReaderBody] » { 

wb: XString.WriterBody *■ XString.NewWriterBodyCmaxLength: FMConverterDef s.TextSize, z: zone]; 

[] «* XString.AppendStream[to: Owb, from: stream, nBytes: FMConverterDef s.TextSize]; 

rb 4- XString.ReaderFromWriterCw: 8wb]t; 

}; 
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— Set the properties for the table and for the frame containing the table 

— d1ml & d1m2 are the parameters for frameDlms In docFrameProps. 
SatPropertlos: PROC[rows, cols, d1ml, dlmZ: CARDINAL] 

RETURNS[tab1eProps: TI .TablePropsRec, docFrameProps: DocInterchangePropsOefs.FramePropsRecord] > { 
tableProps [ -- Set table props 

name: NIL, 

fllUnByRow: TRUE, 

fIxedRows: FALSE, 

f1xedCo1umns: TRUE, 

numberOfColumns : cols, 

numberOf Rows : rows, 

v1s1b1eHeader: TRUE, 

repeatHeader : TRUE, 

repeatTopCaptlon : TRUE, 

repeatBottomCaption : TRUE, 

borderLlne: [none, wl], 

dIviderLlne: [so11d, w4], 

horizontal A1 Ignment : center, 

headerVertlcalAI Ignment: centered, 

topHeaderMargIn: headerMargIn, 

bottomHeade rMarg 1 n : heade rMarg 1 n , 

sortKeys: NIL, 

sparel: 0]; 

docFrameProps «- [ Set table frame props 

borderStyle: solid, 
borderThlckness : 2, 
frameOlms: [d1ml, dImZJ, 
fixedWIdth: FALSE, 
fIxedHelght: FALSE, 
span: fullColumn, 
vertical A1 Ignment: floating, 
horizontal A1 Ignment: centered, 
topMarglnHelght: 0, 
bottomMarglnHelght: 0, 
leftMarglnWIdth: 0, 
rlghtMarglnWIdth: 0, 
sparel: 0]; 

}; 

— call -back proc used to append text to table 
WrlteText: TablelnterchangeDefs.FIHInTextProc ■ { 

r: XStnng. Reader *■ cHentOata; 

TextInterchangeDefs.AppendTextToText[to: text, text: r, textEndContext : XStrlng.unknownContext]; 

}; 

}... 
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\ 

Lab Exercise: GraphicslnterchangeDefs 

^ Graphart 

Explanation of Application: Graphart generates a document with a graphics frame that contains randomly 
placed objects with user specified properties. The application takes a selected document as input and 
enumerates each object in every graphics frame that the document contains. Graphart then modifies the 
properties of the object by choosing a random size and location (orientation and length for lines and 
curves) and by randomly selecting between the property choices specified in the tool. Defaults when no 
values are specified are: Line Style - solid, Line Widths - one pixel, Shades - none. Directions (for lines only) 
- any. The object with its new set of properties is then appended to the destination document. This 
enumeration continues until all objects in the source document have been processed. The newly created 
^ document is then placed on the desktop for your viewing pleasure. 

User interface: The Graphart icon must first be opened as depicted below. The user then selects the desired 
shape for which to set a range of properties (the entire range of properties is selected by default). When 
Graphart encounters an object of the same type in the input document, it will randomly select between 
the values that the user specified. When the line shape is specified, the Shades choices will be replaced by a 
set of possible directions that the user can choose. After setting the desired properties, the user selects the 
desired input document and invokes the Draw Picture command. Graphart produces a blank document 
containing the randomized output from all matching shapes found in ANY Graphics frame within the 
input document. For example, in the figure below, Graphart would set the properties of ALL ellipses 
encountered to: a border with a dotted, double, or dash-dot; a line width of from 1 to 3 pixels; and 50% - 
100% black shading. The other shapes might have different ranges of random values, depending on what 
changes the user made to thei r properties, 




The Graphart tool (as it would appear with a circle selected) & icon 
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The Graphart tool with the line object selected. 



Assignment: In this assignment, you will implement several procedures that enumerate and append 
graphics objects. The procedures are as follows: CreateNewDocument, EnumerateObject, 
FinishNewDocument, GraphicProc, and MakeCurve. Each of these procedures is located in the module 
called GraphartDrawlmplTempiate; additional comments are located in this module. 

Modules: Graphart.config 

GraphartBitmaplmpl.mesa 

G ra pha rt Def s. m esa 

GraphartDrawl m pi Tem pi ate. mesa 

GraphartFormlmpl.mesa 

Graphartlmpl.mesa 

GraphartMsglmpi.mesa 

Hints: CreateNewDocument generates a destination document and obtains its graphics handle; this 
handle is stored in the context for use by other procedures. EnumerateObject is called when a cluster or 
internal graphics frame is encountered; it must enumerate this new container using the same call-back 
procedures as the original enumeration. FinishNewDocument is invoked when the enumeration is 
complete; it must append a graphics frame to the destination document, close the source document, finish 
the destination document, and place it on the desktop. GraphicProc is called for each anchored frame in 
the source document and must enumerate any graphics frames that it encounters (the call-back procs can 
be found by searching for their types). MakeCurve is called when a curve is encountered in the source 
document. MakeCurve generates new properties and adds a curve to the destination graphics handle; 
these new properties can be generated by calling the appropriate Get* procedure. 
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Lab Solution: GraphicslnterchangeDefs 

^ Graphart 

— ■ Copyright (C) Xerox Corporation 1986. A11 rights reserved. 

— This module Implements the Draw command using procs from GraphicslnterchangeDefs. A11 the Make* 
procedures here are EnumProcs for GI .Enumerate. All the Get*Props procedures generate random 

— properties for the objects. SetUpArrays creates arrays from the choices made In the tool; 

— It Implements the random generation of properties. 

" Create a new document and start a graphics frame. 

The handle to the graphics frame will be stored In the data object. 
CreateNawOocuMent: PROCCdata: Defs.Data] » { 

data.newOoc DocInterchangeDefs.StartCreat1onCj.doc; 

data.graphlcsHandle «• GI .StartGraph1cs[doc: data.newDoc]; 

}; 

Enumerate the graphics container passed in as If It were simply another 

— graphics frame. clientOata points to the context. 

EnuaerateObject: PR0C[graph1csConta1ner: DocInterchangeOefs. Instance, clIentData: LONG POINTER] - { 
enumProcs: GI .EnumProcsRecord [ 

clusterProc: Enumerated uster, 

curveProc: MakeCurve, 

elllpseProc: MakeEllipse, 

frameProc: EnumerateFrame, 
''^^^ llneProc: MakeLlne, 

rectangleProc: MakeRectangle, 

triangleProc: MakeTrlangle]; 
data: Defs.Data «- NARROW[ clIentData, Defs.Data]: 
[] GI .Enumerate[ 

doc: data.oldOoc, 

g raph 1 csContal ner : g raph 1 csContal ner , 
procs: OenumProcs, 
clientOata: data]; 

}; 

— Generate a random curve based on the user's data values. Call GetRandomBox to get the location 

— and size of the new curve In the container specified by data.graphlcsHandle. The procedure 
GetCurveProps should be used to get random curve properties. 

MakeCurve: GI. CurveProc " { 
data: Defs.Data «■ NARROW[cl1entOata, Defs.Data]; 
randomBox: GI.Box *• GetRandomBox[data] ; 

randomCurveProps: GI .CurveProps «* GetCurveProp$[data, curveProps, randomBox]; 
GI.AddCurve[ 

h: data.graphlcsHandle, 

box : randomBox , 

curveProps: LOOPHOLE[ randomCurveProps, GI .ReadonlyCurveProps]]; 

}; 
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— Finish the graphics frame and append its content to the new document. Close the old document, 
-- finish the new one, and add the new document to the desktop. 

FinlshNewOocunent: PROCCdata: Defs.Data] - { 
newFile: NSFile. Handle *■ NSFile.nullHandle; 
desktop: NSFile. Handle *■ NSFile. OpenByReference[ 

StarOesktop . GetCu rrentDesktop F i 1 e[ ] ] ; 
graphics: DocInterchangeOefs. Instance ^ 

GI . FinishGraphics[data.graphicsHand1e] ; 
data.f rameProps.f rameOims.w *• data.f rameProps.f rameOims.w / micasPerPixel ; 
data.f rameProps.f rameOims.h *• data.f rameProps.f rameDlms.h / micasPerPixel; 
[] *- OocInterchangeOef s.AppendAnchoredFrame[ 

to: data.newOoc, 

type: graphics, 

anchoredFrameProps: Qdata.f rameProps, 

content: graphics]; 
DocInterchangeDefs.CloseCdocPtr: @data.o1dOoc]; 
[newFile,] *• DocInterchangeDefs.FinishCreation[ 

docPtr: Odata.newOoc, checkAbortProc: DummyAbortProc]; 
NSFile. Move[file:newFi1e, destination: desktop]; 

StarOesktop. AddReferenceToOesktop[reference:NSF11e.GetReference[newF He], place: [0,0]]; 
NSFile. CloseCnewFlle]: 

}; 

DuMyAbortProc: OocInterchangeOef s. CheckAbortProc - {RETURN[FALSE]}; 

— Enumerate through the objects In the source graphics frame and call procedures to add 

-— corresponding objects to the new frame. The dims of the graphics frame are converted to micas 

— and saved in data since all dimensions used later are in these units. 
GraphicProc: OocInterchangeOef s.AnchoredFrameProc » { 

enumProcs: GI.EnumProcsRecord *- [ 

clusterProc: Enumerated uster, 

curveProc: MakeCurve, 

eHipseProc: MakeEHipse, 

frameProc: EnumerateFrame, 

llneProc: MakeLlne, 

rectangleProc: MakeRectangle, 

trIangleProc: MakeTrlangle]; 
data: Defs.Data *■ NARR0W[c11entData, Defs.Data]; 
IF type # graphics THEN RETURN; 
data.f rameProps *• anchoredFramePropst; 

data.f rameProps.f rameDlffls.w *■ anchoredF rameProps.f rameOims.w * micasPerPixel; 
data.f rameProps.f rameOims.h «- anchoredFrameProps. f rameDlms.h * micasPerPixel; 
[] *■ GI .Enumerate[ 

doc: data.oldOoc, 

graphicsContainer: anchoredFrame, 

procs: QenumProcs, 

cllentOata: data]; 

}; 
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Speller 



Lab Exercise: Performance Issues 



Explanation of Application: Speller is a spell-checking tool that allows the user to create a database of 
legal words and then check text against that database for misspelled words. Speller takes input text and 
stores the words in a database. Input text can be a selected document, a selected simple document, 
selected text from anywhere, or the text from the text item within the tool itself. The user can then specify 
text to be spell-checked by the tool. Of course, the user may also delete words from the database. 

User Interface: The Speller icon must first be opened. The user specifies text, either to be inserted into the 
database or to be spell-checked, by either making a selection or by entering text into the Word field of the 
tool. The tool will always attempt to convert the current selection before reading the Word field of the 
tool. 

If the user has the Check Spelling boolean set to true, the Read command will treat the input text as text to 
be spell-checked; conversely, if Check Spelling is false, the f?ead command will treat the input text as words 
to be inserted into the database. Delete interprets the input as words to be deleted from the database. List 
differs from the other commands in that it only takes the first "word" of the input (as defined by XToken) 
as the pattern to find all words in the database that start with that pattern. 

Legal words contain only alphabetic characters (a through z, A through Z). All upper case characters are 
converted to lower case before they're stored in the database. 
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The Speller tool after the L/st command was invoked. 
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Data Structure: The data structure implements a trie (rhymes with "fry"), which is a method of storing 
words by sharing letters in an orderly fashion. This particular trie consists of an array of root elements (a to 
z) where each root element may point to a logical subtree of letters (the subtrees are actually implemented 
in a large array). See the following illustration. 



In this trie, the words a, apt , apple . 
apples . & apply are stored. Child 
letters are indicated with a 
downward arrow, while sibling letters 
are indicated with a sideways arrow. 
Keep in mind that this is only a logical 
structure; in the actual structure, the 
subtree under root element a would 
be implemented in an array. 

The asterisk indicates that this letter is 
the end of a logical word. 



Assignment: In this assignment, you will write code to help improve the performance of the Speller tool. 
Specifically, you will make the Read, Delete, and List commands run in the background, thereby freeing 
the Notifier for other processes. Use the BackgroundProcess interface when forking a process. In addition, 
you should modify the EnumerateDocument procedure so that the document is enumerated in a separate 
NSFile.Session. 



You must not allow the user to run two commands at the same time within the same instance of the 
Speller tool. For example, you can't do a Delete while a List is executing. To facilitate this protection, create 
a boolean called busy and store it in the context. When one of the tool's commands is invoked, set the 
boolean to true so that none of the other commands may be executed until that command finishes. 

Also, you must not let the user close the tool while one of the background processes is executing. 
Therefore, you must write a StarWindowShell.lsCloseLegalProc for the tool. 

You'll need to modify the procedures ReadData, ListData, EnumerateDocument, and DeleteData in 
SpellerFormlmpiTempiate. In addition, you'll have to change SpeilerOefs to add the boolean to the 
context. 

Modules: Speller.config, 

SpellerDefs.mesa, 
SpellerFormlmplTemplate.mesa, 
Spel I er I m pITempI ate. mesa, 
SpellerMsglmpl.mesa, 
SpellerVMimpi.mesa. 
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Lab Solution: Performance Issues 

^ Speller 

If the busy field has not already been added to Spell erOefs.OataObject, then add it as 
the last field: busy: bool «- false 

FromSpellerlmpI: 

MONITOR PROCs - The monitor Invariant Is data. busy 

ensure that process Is finished before destroying context data 
IsCloseLegal : ENTRY StarWindowShell .IsCloseLegalPpoc » { 
body: Window. Handle *■ StarWindowShell .GetBody[sws]; 
data: Defs.Data *■ GetContext[body]; 
IF data. busy THEN RETURNC FALSE]; 
RETURN[TRUE] }; 

From SpellerFormlmpI: 

— MONITOR ENTRY PROCEDUReS 

— data. busy Is the monitor invariant. Refuse requests If another protiess is in progress. 

— Delete the word specified in the form. If the word in 0 chars long post a msg. 

— If the word is found post success message; otherwise, post not found. 
OeleteData: ENTRY FormWIndow.CommandProc = { 

S m iK data: Defs.Data «- Defs.GetCon text [window]; 

IF data. busy THEN RETURN; 
data. busy «- TRUE; 

Process. Detach[FORK DoBackgroundOe1ete[window]] };- 

Called when user wishes to list contents of dictionary. The text in the "word" field of the 

— form is used as a filter (eg if text ■ "to" then a11 words beginning with "to" would be listed). 
LIstOata: ENTRY FormWIndow.CommandProc > { 

data: Defs.Data *■ Def s.GetContextCwindow]; 
IF data. busy THEN RETURN; 
data. busy TRUE; 

Process. Detach[FORK OoBackgroundList[window]] }; 

Reset the monitor Invariant 
MakeBusy False: ENTRY PROC[data: Defs.Data] - {data. busy ^ FALSE }; 

— Gets the currently selected document/simple doc/text/ or word and pa^*ses the information into 

— valid words. Each word is passed off to a procedure to see if it exis'^s in the d-^>:;t1onary; 
--if not the word is saved. When a11 data has been processed, the list of words tliat wore 

— not found is displayed to the user. 
ReadData: ENTRY FormWIndow.CommandProc • { 

data: Defs.Data *■ Defs.GetContext[w1ndow]; 
IF data. busy THEN RETURN; 
data. busy *■ TRUE; 

Process. Detach [FORK OoBackgroundRead[w1ndow]] }; 
.. ENDOFMONTTOR 
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DoBackgroundDeleta: PROCEDURE[window: Window. Handle] » { 
ENABLE UNWIND '> { •- restore monitor invariant 
data: Defs.Data «- Oefs.GetContextCwIndow]; 
MakeBusyFal saCdata]} ; 

RealDelete: BackgroundProcess.Ca11BackProc - { 
data: Defs.Data *• Defs.GetContext[w1ndow]; 

wb: XStr1ng.Wr1terBody <- XStr1ng.NewWriterBody[maxLength: 50, z: Defs.z]; 

xfo: XFormat. Object *■ XFormat.WriterObjectCQwb]; 

text: XStrlng.ReaderBody *- FormW1ndow.GetTextItemVa1ue[ 

window: window. Item: Forml terns. word. ORD, zone: Defs.z]; 
IF XString.EmptyCQtext] THEN { 

rb: XStrlng.ReaderBody *■ Oef s.GetMessage[Oef s.MessageKey.noWordSpecif ied.ORO]; 

Attent1on.Post[Qrb]; 

MakeBusyFal seCdata] ; 

RETURNCf allure]}; 
-- valid data so parse and delete each word 
BEGIN 

rb: XStrlng.ReaderBody; 
word: XStrlng.ReaderBody; 

tokenHandle: XToken. Handle *■ XToken.ReaderToHand1e[r: 8text]; 
DO 

word *■ XToken. F11tered[h: tokenHandle, 

data: NIL, filter: XToken. Alphabetic, skip: nonloken]; 

IF XStrlng.EmptyCQword] THEN EXIT; 

IF Defs.De1eteWord[data, Qword] THEN { 

rb *■ Defs.GetMessage [Defs.MessageKey. deleted. ORD]; 

XFormat. Reader[8xfo, dword]; 

XFormat. Reader[Qxfo, 8rb]; 

XFormat. CR[9xfo]} 
ELSE { 

rb *■ Defs.GetMessage [Defs.MessageKey. not Found. ORD]; 

XFormat. Reader[Qxfo, @word]; 

XFormat. Reader[9xfo, Qrb]; 

XFormat. CRCQxfo]}; 
[] «- XToken. FreeTokenStr1ng[r: Qword]; 
ENDLOOP; 

rb 4- Defs.GetMessage [Defs.MessageKey.de1et1onComp1ete.0RD]; 
XFormat .Reader[Qxfo, Qrb]; 
FormWI ndow . SetTextl temVal ue[ 

window: window, Item: Forml terns. feedback. ORD, newValue: XStr1ng.ReaderFrofflWr1ter[Qwb]]; 
[] «• XToken. FreeReaderHandle[h: tokenHandle]; 
XStr1 ng . FreeReaderBytes[3text , Def s . z] ; 
XStr1ng.FreeWr1terBytes[8wb]; 
END; 

MakeBusyFal se[data] ; 
RETURN[success]; 
}; - of RealDelete 

name: XStrlng.ReaderBody XStrIng . FromSTRING[''De1ete"]; 
Process .SetPr1or1ty[Process . priori tyBackg round] ; 

[] 4- BackgroundProcess.ManageMe[name: Qname, callBackProc: RealDelete]; 

>; 
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— Performs the listing in the background 
DoBackgroundLlst: PROCEDURE[window: Window. Handle] » { 
ENABLE UNWIND >> { " restore monitor invariant 

data: Defs.Data *■ Defs.GetContext[window]; 

MakeBusyFal seCdata]} ; 

RealLlst: BackgroundProcess.Ca11BackProc » { 
wb: XString.WriterBody; 
data: Defs.Data *■ Def s.GetContext[window]; 
text: XString.ReaderBody *• FormWindow.GetTextIte(nVa1ue[ 

window: window, item: FormI terns. wo rd.ORD, zone: Defs.z]; 
tokenHandle: XToken .Handle *• XToken.ReaderToHandleCr: Qtext]; 
word: XString.ReaderBody «- XToken. Fi1tered[ 

h: tokenHandle, data: NIL, filter: XToken. Alphabetic, skip: nonToken]; 
IF XString. Empty [Oword] THEN { 

MakeBusyFal se[data] ; 

RETURN[failure]}; 
wb *■ Defs.List[data: data, r: Glword]; 
FormWindow.SetTextItemValue[ 

window: window, item: FormI terns. feedback.ORD, newValue: XString. ReaderFromWriter[9wb]] ; 
XString. FreeWriterBytes[@wb]; 
[] 4- XToken. FreeTokenString[8word]; 
[] *■ XToken. FreeReaderHandle[h: tokenHandle]; 
MakeBusyFal se[data] ; 
RETURNCsuccess]; 
}; -ofRealList 

name: XString.ReaderBody XString.FromSTRINGC'List"]; 
Process. SetPriorityCProcess. priori tyBackground]; 

[] 4- BackgroundProcess.ManageMe[name: Sname, callBackProc: RealList]; 

}; 
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DoBackgroundRead: PR0CEDURE[w1ndow: Window. Handle] > { 
ENABLE UNWIND { - restore monitor invariant 

data: Defs.Oata «- Defs.GetContextCwIndow]; 

MakeBusyFal se[data]} ; 

RealRead: BackgroundProcess.CallBackProc - { 
data: Defs.Data <- Defs.GetContext[window]; 
blank: XString.ReaderBody *■ XStr1ng.FromSTRING[" "L]; 
head: NotFoundPtr Def s .z.NEW[NotFoundNod9 *- 

[word: XString.CopyToNewReaderBodyCr:@b1ank, zrOefs.z]]]; 
check: BOOLEAN <- FormW1ndow.GetBoo1eanIteniVa1ue[ 

window: window, item: Formltems.checkSpelUng.ORD]; 
text: XString.ReaderBody; 
f1na1Status *• success; 
BEGIN 

ENABLE 

BEGIN 

FlleProblem => {MakeBusyFal seCdata]; GOTO Ex1t>; 
NoSelectlon «> { 

text *• FormW1ndow.GetTextItemValue[ 
window: window. Item: Formltems.word.ORD, zone: Defs.z]; 

CONTINUE}; 
FllelsDoc >> { - d€Ks are handled separately 

EnumerateDocument[data, check, head, window]; 

MakeBusyFalse[data]: 

GOTO Exit}; 
END; 

text *- GetSe1ect1onAsReader[data]; 
END; 

CheckTextCdata, Qtext, check, head]; 

XStr1ng.FreeReaderBytes[8text, Defs.z]; -free the checked text 
IF check THEN D1sp1ayWordsNotFound[head, window] 

ELSE { 

rb: XString.ReaderBody *- Defs.GetMessageCDefs.MessageKey.lnsertlonComplete.ORO]; 

FormWIndow.SetTextltemValueCwIndow: window, Item: Formltems. feedback. 0R0,newVa1ue: Orb]}; 
MakeBusyFal se[data] ; 
EXITS Exit =>•> NULL; 

>; 

name: XString.ReaderBody ♦■ XStr1ng.FromSTRING["Read"]; 
Process. SetPr1or1ty[Process. priori tyBackg round]; 

[] *- BackgroundProcess.ManageMeCname: Qname, callBackProc: RealRead]; 

}; 
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— Open and enumerate the selected doc. Check each word of text to see 1f it is in the dictionary 
EnunerateDocuMnt: PROC[ 
data: Defs.Data, check: BOOLEAN, head: NotFoundPtr, window: Window. Handle] - { 

check each block of text found in the document 
TextProc: DocInterchangeDefs.TextProc ' {CheckText[data, text, check, head]}; 

element: Selection. Value ♦• Selection. Convert[file]; -get reference to file 

ref : LONG POINTER TO NSFile. Reference «* element .value; 

enumProcs: DocInterchangeOefs.EnumProcsRecord ♦- [textProc: TextProc]; 

status : OocInterchangeOef s .OpenStatus ; 

doc: OocInterchangeOef s. Doc; 

user: Atoa.ATON «- Aton.MakeAtomC'CurrentUser'L]; 

prop: Atoa.ATON <- At0M.MakeAt0M["Ident1tyHand1e"L]; 

identity: Auth.IdentltyHandle = Atoii.GetPropCuser, prop]t. value; 

session: NSFIIo. Session *■ NSFile. Logon£1dent1ty]; 

— open source document and enumerate in a separate NSFile session 

[doc, status] *■ DocInterchangeDefs.0pen[docF11eRef : reft, session: session]; 

IF status # ok THEN GOTO Exit; 

[] «- OocInterchangeOef s.Enumerate[ 

textContainer: [docCh :doc]] , procs: QenumProcs, clientOata: head]; 
Doclnte rchangeOef s . CI ose[docPt r : 8doc] ; 
NSF i 1 e . Logoff [sess i on] ; 

IF check THEN DisplayWordsNotFound[head, window] 

ELSE { 

rb: XString.ReaderBody «- Defs.GetMessage[Defs.MessageKey.insertionComplete.ORD]; 
FormWi ndow . SetTextl temVal ue[ 
window: window, item: FormI terns. feedback.ORO, newValue: drb]}; 
EXITS Exit »> { 

rb: XString.ReaderBody «- Defs.GetMessage[Defs.MessageKey .problemsWithOoc.ORD]; 
Attention . Post[Qrb]} ; 

}; 
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DoclnterchangeDefs 
(and other Interfaces) 

*** DRAFT Documentation *** 



ChartDatalnstallDefs 



61.1 Overview 

ChartDatalnstaiiOefs provides the ability to install new data in a chart without regard to 
the type of the chart. Specifics such as line styles or shadings are not affected. Typical 
clients include those that have changing data depicted in chart form (e.g., one such client 
is the ViewPoint database package). 

61.2 Interface Items 

The primary type in this interface is the Handle, which points to a record of chart 
information. Clients may obtain a handle by either calling GetChartFromlnstance or 
GetChartFromSelection. Once the client has a handle, several functions can be performed 
on the chart; installing new data or validating the chart are some examples. 

Handle: type ■ long pointer to Object; 

Object: type « record [ 
type: ChartType, 

instance: OoclnterchangeOefs.lnstance, 

vaiidateChart: ValidateChartProc, 
valfdateOata: VaiidateOataProc, 
plot: PlotProc, 
free: FreeProd; 

ChartType: type ■ machine dependent {bar(O), lined), pie(2), last(15)}: 

type refers to the manner that the chart displays information, instance is a record that has 
pointers to the chart data. vaiidateChart is a call-back procedure to check if the chart can 
be edited. validateOata checks the validity of new data to be installed in the chart, plot 
actually installs the data, while free releases the handle. 

ValidateChartProc: type » PROc[h: Handle] 
returns [ChartValidityj; 

ChartValidity: type « machine dependent {ok(0), closed(1), readOnly(2)Jast(1 5)}; 
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VaiidateChartProc checks the chart and returns its status. This procedure should be called 
before any attempt to operate on the chart. 

VaiidateOataProc: type » proc [ 
h: Handle, 
data: Data, 
changes: Selections] 
RETURNS [Data Validity]; 

OataValidity: type > machine dependent record [ 
v(0): SELECT result(0): OataValidity Result from 

ok a > NULL, 

invaiidSource ■ > null, 

sizeMismatch ■ > [extraRows(l): integer, extraCols(2): integer], 
nonNumericValue ■ > [row(1): cardinal, coI(2): cardinal], 
iilegaiValue ■ > [row(1): cardinal, coi(2): cardinal], 
unknown ■ > null, 

last a > NULL, 

endcase]; 

DataValidityResult: type ■ machine dependent { 

ok(0), invalidSource(l), sizeMismatch<2), nonNumericValue(3), illegal Value(4), 
unknown(5), last(15)}; 

VaiidateOataProc checks the validity of the new data that the client intends to install. The 
data is not actually installed in this step, data is a pointer to the current data, changes 
specifies which items are being validated. 

OataValidity indicates the validity of the data and in the case of bad data, some additional 
information. extraRows is the number of extra rows the new data has relative to the 
chart's current data table. A negative number means the chart currently has more rows 
than the data. extraCols is the analagous number for columns, row and col indicate the 
position of the charts problem. 

PlOtPrOC: TYPE ■ PROC ( 

h: Handle, 
data: Data, 
changes: Selections]; 

Selections: TYPE ■ packedarray Values of boolean; 

ail: Selections ■ allCtrue]; 

Values: type ■ {title, data, rowLabels, colLabels, orientation}; 

PlotProc sets the chart's data and then redraws the chart, data is a pointer to the new data 
to be installed, changes specifies exactly which data is set. 

Oata:TYPE ■ long pointer to OataRec; 

OataRec: type ■ record ( 
title: xstring.Reader 4-NiL, 
data: Oata Values, 
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rowLabeis: Labels <-niu 
coiLabeis: Labels <-niu 
orientation: Orientation 4-row]; 

OataVaiues: type ■ long pointer to RowSeq; 

RowSeq: TYPE » record [ 

rows: SELEa format: OataFormat from 
string ■ > [sequence nRows: cardinal of StringRow]« 
numeric ■ > [sequence nRows: cardinal of NumericRow] 

endcase]; 

DataFormat: type • {string, numeric}; 
Labels: TYPE * long pointer to LabeiSeq; 

LabelSeq: type ■ record [sequence length:cARDiNAL of xstring.Reader]; 
Orientation: type a {column, row}; 



DataRec contains the data to be installed- title is the title of the chart, data points to a 
sequence-containing record of data values. rowLabels and coiLabeis point to sequence- 
containing records of row and column labels, respectively, orientation speciHes Whether 
columns or rows are the chart's data sets. 

StringRow: type ■ long pointer to StringRowElements; 

StringRowElements: type ■ record [sequence nCols: cardinal of xstrmg. Reader]; 

NumericRow: TYPE ■ long pointer TO NumericRowEiements; 
NumericRowElements: type ■ record [sequence nCois: cardinal of xLReai.Number]; 

StringRow points to a sequence-containing record of readers; similarly, NumericRow 
points to a sequence-containing record of numbers. 

Hence, the data to be installed looks like Figure 61.1: 

GetChartFrominstance: proc [instance: oocinterchangeOefs.lnstance] 
returns [Handle]; 

This procedure returns a handle to the chart given by instance. The result will be nil if the 
instance is not a chart. Note that a non-NiL handle doesn't guarantee that the chart is 
valid; it only guarantees that the instance is a chart. Clients should call the chart's 
validateChartProc to determine the chart's validity. 

GetChartFromSeiection: proc returns [Handle]; 

This procedure obtains a handle by converting the current selection. If the current 
selection is not a chart, nil will be returned. 

FreeProc: TYPE ■ PROC[h: Handle]; 

FreeProc frees the handle passed in by GetChartFromSelection or 
GetChartFrominstance. 
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Data 



DataRec 

title data rowLabeis coiLabeis orientation 

dm 



OataValues 



RowSeq 





























StringRow / NumericRow 



String RowElements / 
NumericRowElements 



Labels 



7 



Labe Seq 



XString. Reader 
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Labels 



LabelSeq 



XString. Reader 



title is an xstring. Reader, 
orientation is an enumerated. 



Figure 61.1 



OutOfRoomForGraphics: error; 



Raised by handle.plot if there is no more room in the document to insert graphic object 
(the components of charts). 



61.3 Usage 



The typical pattern of use for this module is: 



handle <- GetChartFromSeiectionG 
IF handle # NIL THEN { 

00 

< < get raw data; > > 

IF handle. valldateChartfhandlel # ok then {< < error; > > loop}; 

< < determine which pieces of data are to be changed > > 
<< allocate and fillin data record > > 

IF handle. validateOata[handle, data, selections] # ok then < < error; > > 
handle.piot[handle, data, selections]; 

ENDLOOP; 

handle.free{handie]; 

}; 
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62.1 Overview 

The DocInterchangeDefs interface enables clients to create a new ViewPoint document or 
read an existing one. However, it does not support inserting new information or changing 
or deleting the contents! of a document. 

i 

DocInterchangeDefs provides procedures to create or read any of the basic document 
structures, such as text; textual "tiles;" fields; headings and footings; or frames of various 
types. It does not include procedures to manipulate contents of frames, however. 

To create content within frames, the client must use interfaces specific to a particular 
frame type. GraphlcslnterchangeDefs provides facilities for creating or reading graphics 
frames; Table! nterchangeOefs provides facilities for creating or reading tables; 
TextlnterchangeOefs provides facilities for creating or reading text frames. These are 
currently the only frame content interfaces available. 

62.1.1 Creating Documents 

To create a ViewPoint document, the first step is to call the procedure StartCreation. This 
sets up the data structures for the document and returns a Doc, which is a long pointer to 
an opaque type that represents the document. With TextlnterchangeDefs, the client calls 
AppendAnchoredFrame first and then uses TextlnterchangeDefs to append information 
to the text frame 

The next step is to add information to the document with various Append* procedures: 
AppendAnchoredFrame, AppendChar, AppendColumnBreak, AppendField, 
AppendNewParagraph, AppendPageBreak, AppendPFC (Page Format Character), 
AppendText, or AppendTile. 

With AppendAnchoredFrame, the client would typically call GraphlcslnterchangeDefs or 
TablelnterchangeDefs to create the contents of the frame, and then call 
AppendAnchoredFrame to add that frame and its contents to the document. 
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AppendFieid, AppendPFC, and AppendTile all have return values: this allows the client to 
call Append* routines recursively to add text and formatting information to fields, tiles, 
or PFC headers. 

When the document contains all the desired information, the client should call 
FinishCreation, which returns an NSFile.Handle for the newly created file. 

62.1.2 Enumerating documents 

To enumerate the contents of an existing ViewPoint document, the client should start by 
calling Open, which opens the document and returns a Ooc handle for that document. The 
next step is to call Enumerate, passing in the Ooc and an EnumProcs record. The 
EnumProcs record contains a set of callback procedures, one for each of the following 
structures: anchored frame, column break, field, new paragraph, page break, page format 
character, text, tile. 

Enumerate proceeds sequentially from the beginning of the document: as it comes to 
different structures within the document, it calls the appropriate callback procedure, 
which handles it appropriately. Each of these procedures returns a boolean value stop; if 
any one of the procedures returns stop = true, the enumeration will terminate. If stop is 
never true, the enumeration will continue to the end of the document. 

When the enumeration is complete, the client should call Close to free all associated data 
structures and close any open file handles to the document. iiB|| 

62.2 Interface Items 



62.2.1 Datatypes 

The basic data structure of DoclnterchangeOefs is the TextContainer, which is any object 
that can contain text. A TextContainer can be a caption, document, field, heading, footing, 
or spare (spares are for future compatability). 

TexKontainer: type ■ record [ 
var: SELEcrtype: *from 

caption ■ > [h: Caption], 

doc ■ > [h: DocL 

field « > [h: Field], 

heading ■ > [h: Heading], 

footing ■ > [h: Footing], 

sparel ■ > [h: SpareTC], 

spareZ ■ > [h: SpareTC], 

spares ■ > [h: SpareTC], 

spare4 a > [h: SpareTC], 
enocase]; 

Caption: TYPE a long pointer to CaptionObject; 
CaptionObject: type; 
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Doc: TYPE ■ LONG POINTER TO OocObject; 
DocObject: type; 

Field: TYPE ■ long pointer to FieidObject; 
FieldObject: type; 

Heading: TYPE a long pointer to HeadingObject; 
HeadingObject: type; 

Footing: TYPE • long pointer to FootingObject; 
FootingObject: type; 

Tile: TYPE * long pointer TO TileObject; 

TileObject:TYPE;Footing: TYPE ■ long pointer to FootingObject; 
SpareTC: TYPE a LONG unspecified; 

Note that TextContainers must contain at least one newParagraph character, since the 
paragraph properties of any text are always inherited from the preceding newParagraph 
character. The Doclnterchange implementation supplies the initial newParagraph 
characters as required; the client should assume they already exist. 



62.2.2 Creating documents 



62.2.2.1 Initializing a document 

The client calls StartCreation to initiate the document creation process. 

StartCreation: proc[ 

paginateOption: PaginateOption compress, 
wantHeadingHandies, wantFootingHandles: bool4- false, 
initialFontProps: Oocint«rchangePropsO«fs.ReadoniyFontProps <- nil, 
initiaiParaProps: 0ocinterchangeProps0«fs.ReadonlyParaProps *- nil, 
initiaiPageProps: oocinterchangePropso«fs.ReadoniyPageProps 4-nil] 
returns [ 
doc: Ooc, 

leftHeading, rightHeading: Heading, 
leftFootlng, rightFooting: Footing, 
status: StartCreationStatusl; 

PaginateOption: TYPE ■ machine dependent { 

none(0), simple, compress, firstAvailable, lastAvailable(255)}; 

paginateOption specifies the type of pagination that will occur when the client calls 
FinishCreation. It is specified here rather than in FlnishCreation to enable performance 
optimizations based on the type of pagination that will eventually occur. 

compress pagination provides all the outward signs of pagination, such as page format 
properties, and leaves the structure of the document in its optimized form. 
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simple pagination provides the outward signs of pagination but does not leave the 
document in its optimized form, so subsequent editing may be slower than with 
compress pagination, simple pagination is slightly faster than compress. 

none leaves the document in its raw form. This can lead to very slow editing, and 
potentially to loss of data. If the document will be more than a few pages long, client 
must specify a paginateOption other than none to avoid losing data. 

wantHeadingHandles and wantFootingHandies specify whether the document will have 
headings and footings. 

initialFontProcs. initialParaProcs, and initialPageProps specify the initial properties for the 
document. If you do not specify a field of initial properties, StartCreation will use the 
document default properties. (For information on document default properties, see the 
DocInterchangePropsDefs chapter) 

In the pageProps, the client must ensure that the page margins leave at least one inch (72 
points) for text. That is, (left margin + right margin + 72 <= page width), and (top 
margin 4* bottom margin +72 < = page height). 

StartCreation returns a Doc handle, handles for headings and footings, and a status. The 
Doc handle represents the new document. The client should pass this handle to the 
Append* procedures described below to add information to the document, and then 
eventually release the handle with a call to FinishCreation. 

If the client releases the handle without ever calling any Append* routines, the file will 
contain a 1-page document containing a single newParagraph and pageFormat character, 
with the initial font, paragraph, and page props as specified. 

The heading and footing handles that are returned will be nil unless the client specified 
wantHeadingHandles or wantFootingHandies = true. If the headings or footings are 
valid, the client should call various Append* routines to add text and formatting 
information, and then later release each handle with a call to ReieaseHeading or 
ReleaseFooting. See section 62.2.2.3 for details. 

StartCreationStatus: TYPE ■ machine dependent { 

oic(O), notEnoughOiskSpace, notEnoughVM, firstAvailable, lastAvailable(255)}; 

StartCreation returns a status code, which can have any of the following values: 

ok Everything was fine. 

notEnoughOiskSpace There isn't enough disk space to perform the operation. 
notEnoughVM There isn't enough contiguous virtual memory to create. 

63.2.2.2 Adding to a document 

The Append* routines below add various kinds of information to TextContainers. 

AppendChar, AppendField, AppendNewParagrapii, AppendText, and AppendTile take a 
TextContainer as a parameter and add the specified information to that container. The 
remaining procedures (AppendAnchoredFrame, AppendColumnBreak, 
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AppendPageFormatCharacter, AppendPageBreak) take only a Doc, and not a general 
purpose TextContainer; other TextContainers cannot contain the various special 
characters. 



With all of these procedures, the client must manage the storage for the property records 
or other data structures passed in, except for handles obtained from the interface itself. 
The storage for the properties must remain valid during the call to Append*; after 
Append* returns, the client may do anything it chooses with the storage (typically, free 
it.) 

The Append* procedures often allow the client to set font, paragraph, or page properties. 
Defaulting any of these arguments will cause the newly appended text or object to inherit 
the properties of the preceding text/object and not the application- wide default properties. 

If an Append* routine returns a non-NiL handle, the client is responsible for later freeing 
that handle with a call to an appropriate Release* routine. See section 63.2.2.3 for 
details. 

AppendAnchoredFrame: proc [ 
to: Doc, 

type: AnchoredFrameType, 

anchoredFrameProps: DocinterdiangePropsOefs.ReadoniyFrameProps, 
content: Instance instanceNil, 
wantTopCaptionHandle, wantBottomCaptionHandie, 
wantLeftCaptionHandler wantRightCaptionHandle: bool *- false, 
anchorFontProps: oocinterchangePropsOefs.ReadonlyFontProps «-nil] 

RETURNS [ 

anchoredFrame: Instance, 
topCaption, bottomCaption, 
leftCaption, rightCaption: Caption]; 

AppendAnchoredFrame appends the anchored frame type with properties 
anchoredFrameProps to the document Doc. 

AnchoredFrameType: type ■ machine dependent { 

nil(O), bitmap, cuspButton, equation, graphics, IMG, table, text, 
illustrator, firstAvailable, iastAvailabie(2S5)}; 

content is the contents of the frame. Currently, there are interfaces to support creating 
graphics frames, tables, and text frames. For information on creating graphics frames, 
cuspButtons, or bitmap frames, see GraphicslnterchangeDefs. For information on 
creating table content, see Table! nterchangeOefs. For information on creating text frames 
see TextlnterchangeDefs. 

want*CaptionHandle specifies which captions the frame should have. anchorFontProps 
specifies the font properties of the frame anchor. Changing the font properties of the 
anchor does not affect how that anchor appears on the display, but does affect the default 
properties that succeeding characters will inherit. 

AppendAnchoredFrame returns handles to the frame and its captions. The caption 
handles will be non-NiL only if the client specified true for the corresponding 
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want^CaptionHandle parameter. The client must later release each valid caption handle 
with ReieaseCaption. 

The return parameter anchoredFrame is currently used only by the TextlnterchangeDefs 
interface for appending text frames. 

AppendChar: proc [ 
to: TextContainer, 
char: xchar.Character, 

fontProps: OocinterchangePropsOefs.ReadoniyFontProps 4- NIL, 
nToAppend: cardinal 1]; 

AppendChar appends one or more copies of the text character char to the specified 
TextContainer. nToAppend specifies the number of copies of the character that are to be 
appended; fontProps specifies the character properties. 

AppendColumnBreak: proc[ 

to: Doc, fontProps: oocinterchang«PropsOefs.ReadonlyFontProps ^-nil]; 

AppendColumnBreak appends a column break character to a document. fontProps are the 
properties of the column break character; these properties do not affect the appearance of 
the character itself, but they do affect the properties that succeeding characters will 
inherit. 

AppendFieid: proc[ 
to: TextContainer, 

fieidProps: DocinterchangePropsOefs.ReadonlyFieldProps, 
fontProps: OocinterchangePropsOefs.ReadonlyFontProps <- Nil.] 
returns [field: Field]; 

AppendFieid appends a field to the specified TextContainer. AppendFieid returns a field; 
the client can then add information to the field by using the Field as the TextContainer in 
other calls to Append* routines (but not AppendFieid again.) When the client is through 
with the field, it must release it via ReieaseFieid. See section 62.2.2.3. 

Note that the client cannot set the fill-in order of the fields when they are appended to the 
document. 

AppendNewParagraph: proc[ 
to: TextContainer, 

paraProps: oocinterchangePropsOefs.ReadonlyParaProps ^nil, 
fontProps: 0<KinterchangePropsO«fs.ReadonlyFontProps 
nToAppend: cardinal 1]; 

AppendNewParagraph appends one or more new paragraph characters to a 
TextContainer object. nToAppend specifies the number of characters to be appended. 
paraProps and fontProps specify the properties for the paragraph. If paraProps is nil, the 
new paragraph inherits the props of the previous paragraph; otherwise, paraProps 
determines the properties of the paragraph. 
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Note that TextContainers always contain at least one newParagraph character. The client 
does not have to provides these initial newParagraph characters; Oodnterchange 
implementation supplies them as required. 

AppendPageBreak: proc [ 

to: Doc, fontProps: Oocint«rchangePropso«fs.ReadonlyFontProps 4-nil]; 

AppendPageBreak appends a page break character to the text of a document. The 
fontProps do not aiTect the appearance of the page break character itself, but they do affect 
the properties that succeeding characters will inherit. 

AppendPFC: PR0C[ 
to: Ooc, 

pageProps : DodnterchangePropsOaf s. Readon I y PageProps, 
wantHeadingHandles, wantFootingHandles: bool«>- false, 
fontProps: oocinterchang«PropsO«fs.Readoniy FontProps «-nil] 

RETURNS [ 

leftHeading, rightHeading: Heading, 
leftFooting, rightFooting: Footing]; 

AppendPFC appends a page format character to the main document text. 

pageProps specify the properties for the new page. The client must ensure that the page 
margins leave at least one inch (72 points) for text. That is, (left margin + right 
margin -f 72 < ■ page width), and (top margin ^ bottom margin 72 < ■ page height). 

The heading and footing handles that are returned will be nil unless the client specified 
wantHeadingHandles or wantFootingHandles = true. 

If the heading and footing handles are valid, the client can then use them as 
TextContainers for further calls with Append"* procedures. If the headers are to be the 
same on left and right pages, only leftHeading need contain the heading; rightHeading 
should be nil. The same rule applies for leftFooting and rightFooting. 

When creating a heading or footing, the client should note that there are no automatic 
positioning parameters for information in headers and footers; the client must call the 
appropriate Append* procedures to add the desired text and position it with standard text 
formatting, such as white-space characters, paragraph alignment, leading, line height, 
and tabs. 

Additionally, there is no page number pattern; the client must place any surrounding text 
directly in the heading/footing text, inserting the # character at the position(s) where a 
page number is desired. (Note that there is a procedure, 
Oocint«rchangePropsO«fs.GetPageNumberOeiimiter, that returns this character.) 

The client must later free every non-NiL heading or footing with a call to ReleaseHeading 
or ReleaseFooting. 

AppendText: proc [ 
to: TextContainer, 
text: xstrtng. Reader, 
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textEndContext: xstring.Context, 

fontProps: oocinterchang«Propso«fs.ReadoniyFontProps <-nil1; 

AppendText appends the text with the specified properties to the TextContainer. For 
ei!iciency, the client should pass the appropriate textEndContext if it is known (just like 
xstring.AppendReader). 

AppendTile: proc[ 
to: TextContainer, 
type: Atom.ATOM, 
data: long pointer nil, 

fontProps: oocinterchangePropso«fs.Readoniy FontProps 4-nil] 
RETURNS [tile: Tile]; 

AppendTile is for future use. The tile type and data format are defined elsewhere, agreed 
upon by parties on either side of this interface. 



62.2.2.3 Releasing storage 

ReleaseCaption: proc (captionPtr: long pointer to Caption]; 
ReieaseFleid: proc [fieidPtr: long pointer to Field]; 
ReieaseHeadIng: proc [headingPtr: long pointer to Heading]; 
ReleaseFooting: proc [foot! ngPtr: long pointer to Footing]; 
ReleaseTile: proc [tiiePtr: long pointer to Tile]; 
ReleaseSparel : proc [ptr: long pointer to SpareTC]; 
ReieaseSpare2: proc [ptr: long pointer to SpareTC]; 
ReleaseSpareB: proc [ptr: long pointer to SpareTC]; 
ReleaseSpare4: proc [ptr: long pointer to SpareTC]; 

The client must call ReleaseCaption, ReleaseField, ReleaseFooting, ReleaseHeading, 
ReleaseTile. or ReieaseSpare to release resources associated with any non-NiL handle 
obtained from any Append* procedure. 

After calling Release*, the handle will be invalid. To help prevent use of an invalid 
handle, the Release* routines take a pointer to the handle, and set the handle itself to nil. 
(This is similar to Mesa's free operation.) 



62.2.2.4 Finalizing a document 

FinishCreation: proc[ 

docPtr: long pointer to Doc, 
checkAbortProc: CheckAbortProc «-nil, 
checkAbortClientOata: long pointer 4- nil] 
returns [ 
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docFiie: NSFiie.Handle. 
session: NSFii«.Session, 
status: FinishCreationStatus]; 



When the document is complete, the client must call FinishCreation to finalize the 
document and release the Ooc handle. FinishCreation returns an NSPti«.Handle to the 
newly-created document, an NSFila.Session, and a status. The file handle is valid in the 
returned NSFile session. The session returned will be the default session if the client 
called FinishCreation normally (not by a forked background process). If StartCreation was 
called by a forked background process, then the returned session will be a private session 
created by StartCreation. The client must kill this private session by calling 
NSFile.LogoffCsessionj after it's finished processing the document file. The document that 
FinishCreation provides will be in paginated form if the client so specified in 
StartCreation. 

CheckAbortProc: type ■ PROC[ciientOata: long pointer] returns [abort: bool]; 

If the client specified a checkAbortProc, then a call-back procedure will be invoked before 
the call to FinishCreation returns; this call-back can abort the document's completion. 
checkAbortClientOata is a client defined argument and is passed into the call-back 
procedure. 

FinishCreationStatus: TYPE * machine dependent {ok(0), 

aborted, okButNotEnoughOiskSpaceToPaginate, okBuNotEnoughVMToPaginate, 
okButUnknownPaginateProbiem, firstAvailabie, iastAvaiiable(255)}; 

FinishCreation also returns a status code, which can have any of the following values: 



aborted do not complete the document. 

okButNotEnoughOiskSpaceToPaginate, 
OkBuNotEnoughVMToPaginate, 

okButUnknownPaginateProbiem the document is finished but left unpaginated 

This document file is temporary, and will be purged from the NSFile system if a reboot 
occurs before it is made permanent. To make the file permanent, the client should call 
move it to the current user desktop with NSFiia.Move, followed by a call to 
starO«sktop.AddReference to put the icon on the display. (See section 62.3 for an example of 
this.) 

AbortCreation: PROcIdocPtr: long pointer to Ooc]; 

AbortCreation aborts document creation and deallocates the storage associated with that 
document. 

62.2.2.5 Utilities 

The following procedures are utilities that may be of use to the client creating a document. 

GetModeProps: PROc[doc: Ooc, modeProps: Do€interchang«PropsO€fs.ModeProps]; 

SetModeProps: procI 
doc: Ooc, 
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modeProps: oo€interchangePropso«fs.ReaclonlyMociePropSr 
selections: oocinterchang«Propso«fs.ModeSelections]; 

Get or set the mode properties for the document; these procedures may be called at any 
time. When setting mode properties, only those properties designated by true selections 
will be changed. 

SetCurrentParagraphProps: proc [ 
textContainer: TextContainer, 
paraProps: 0ocint«rchangePropsOefs.ReadonlyParaProps]; 

SetCurrentParagraphProps can be called at any time, such as in the middle of a paragraph 
or (even if it makes no sense) repeatedly with different properties. If it is called repeatedly, 
only the most recent call will remain in effect. The client can call this procedure on any 
TextContainer, such as a document. 

SetCurrentParagraphProps affects the entire current paragraph, including any portion 
not yet appended at the time it is called. The properties also affect all subsequent 
paragraphs unless the client overrides the properties with new ones passed to 
AppendNewParagraph, or by another call to SetCurrentParagraphProps. 

Note, however, that setting paragraph properties on a TextContainer will cause an error if 
that TextContainer does not contain any paragraph characters. Although Ooclnterchange 
does guarantee that every TextContainer will contain at least one new paragraph 
character, those paragraph characters are added (if necessary) during the Append* 
routines. Thus, calling SetCurrentParagraphProps before calling any Append* routines 
will cause an error. To avoid this problem, the client can simply call AddNewParagraph 
to ensure that the TextContainer does have a paragraph character. Since the Append* 
routines only add a new paragraph if necessary, this will not cause duplication. 



62.2.3 Enumerating documents 

62.2.3.1 Open 

Open: proc[ 

docFiieRef: NSFiie.Reference, 
session: NSFUs.Session 4-NSFii«.nullSession, 
password : xstring. Reader *~ nil] 
RETURNS [doc: Ooc, status: Open Status]; 

To enumerate a document, the first step is to call Open. Open takes a NSFiie.Reference for a 
file and opens it for reading in the NSFiling session specified by the session argument. 
The client should then pass Doc returned to Enumerate, which will parse the document. 

password is provided in anticipation of future password-locking of documents, password 
is currently ignored. 

OpenStatus: TYPE a machine dependent { 

ok(OK malFormed, incompatible, notLocal, outOf DiskSpace, outOfVM, busy, 
invalidPasswordr firstAvai table, iastAvaiiable(255)}; 
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Open also returns a status code, which can have any of the following values: 



ok 

mai Formed 
incompatible 

notLocal 
outOfDiskSpace 
outOfVM 
busy 

invaiidPassword 
62.2.3.2 Enumerate 



Everything was fine 

The Document is inconsistent internally. 

The document is more than one version old, and the upgrader 
cannot handle it. 

The document is not on the workstation, so it cannot be opened. 

There isn't enough disk space to open the document. 

There isn't enough contiguous virtual memory. 

Another process is using the file (e.g. background pagination). 

The user does not have the credentials to open the document. 



Enumerate: proc [ 

textContainer: TextContainer, 
procs: EnumProcs, 
ciientOata: long pointer*- nil] 
RETURNS [dataSkipped: bool]; 

Enumerate parses the contents of the specified TextContainer. 



procs is a record that contains client-defined callback procedures to enumerate the various 
kinds of structiures that can be found in a TextContainer. 



EnumProcs: TYPE ■ long pointer to EnumProcsRecord; 

EnumProcsRecord: type > record [ 

anchoredFrameProc: AnchoredFrameProc <-nil, 
columnBreakProc: CoiumnBreakProc 4-nil, 
f ieldProc: FieidProc nil, 
newParagraphProc: NewParagraphProc <-nil, 
pageSreakProc: PageBreakProc ^-nil, 
pfcProc: PFCProc <-nil, 
textProc: TextProc <-nil, 
tileProc: TileProc 4-nil, 
sparelProc: SpareProc ^-nil* 
spare2Proc: SpareProc *- nil, 
spare3Proc: SpareProc «-niu 
spare4Proc: SpareProc ^-nil]; 

Each of the procedures in an EnumProcsRecord takes as parameters the properties of the 
structure and its content when appropriate. Note that the storage for the properties passed 
to these procedures is temporary; the client must explicitly copy any properties it wishes to 
save. For a description of the various properties, see the corresponding Append* routines. 

AnchoredFrameProc: type ■ proc[ 
ciientOata: long pointer, 
type: AnchoredFrameType, 
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anchorFontProps: OocinterchangePropsOefs.ReadonlyFontProps, 
anchoredFrame: Instance, 

anchoredFrameProps: oocinterchangePropsOef$.ReadonlyFrameProps, 

content: Instance, 

topCaption, 

bottomCaption, 

leftCaption, 

rightCaption: Caption] 

RETURNS [stop: BOOL 4- FALSE]; 

Instance: type{2]; 

instanceNil: instance ■ loophole[long(0]]; 

Column BreakProc: TYPE ■ proc[ 
ciientOata: long pointer, 

fontProps:DocintsrchangePropso«fs.ReadoniyFontProps] 

RETURNS [stop: BOOL 4- FALSE]; 

FieldProc: type ■ proc [ 
cilentData: long pointer, 

fontProps: oodnterchang«PropsOef 5. Readonly FontProps, 
fieldProps: oodnt«rchangePropso«fs.ReadonlyFleidProps, 
field: Field] 

RETURNS [stop: BOOL 4- FALSE]; 

NewParagraphProc: TYPE ■ proc[ 
ciientOata: long pointer, 

fontProps: DodnterchangePropsOefs.ReadonlyFontProps, 
paraProps:Docint«rchangePropsOefs.ReadonlyParaProps] 

RETURNS [stop: BOOL 4- FALSE]; 

PageBreakProc: type ■ proc [ 

ciientOata: long pointer, 

fontProps: Do<interchang«Propso«fs.ReadoniyFontProps] 

RETURNS [stop: BOOL 4- FALSE]; 

PFCProc: type ■ proc ( 

ciientOata: LONG POINTER, 

fontProps: Do<int«rchangePropsOefs.ReadonlyFontProps, 
pageProps: OocinterchangePropsoefs.ReadoniyPageProps, 
leftHeading, rightHeading: Heading, 
leftFooting, rightFooting: Footing] 

RETURNS [stop: BOOL 4~ FALSE]; 

In a PFCProc, if the headers are the same on left and right pages, only leftHeading will 
contain the heading; rightHeading will be nil. (Of course, leftHeading can be nil if it has no 
content.) The same rule applies for leftFooting and rightFooting. 

TextProc: type ■ proc [ 

ciientOata: long pointer, 

fontProps: Do<interchangePropsOefs.ReadonlyFontProps, 
text: xstring. Reader. 
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textEndContext: xstring.Context] 

RETURNS [stop: BOOL «- FALSE]; 

In a TextProc, textEndContext will always be accurate; it will never be 
xstring.uni(nownContext. 

TileProc: type ■ proc ( 

clientOata: long pointer, 

fontProps:Docinter€hang«Propso«fs.ReadonlyFontProps, 
type: Atom.ATOM, 
data: long pointer, 
tile: Tile] 

returns (stop: bool 4- false] ; 

SpareProc: type « proc[ 
clientOata: long pointer, 
data: long unspecified] 
returns [stop: bool 4- false]; 

As it encounters an object of a particular type. Enumerate will call the appropriate 
procedure. If the client defaults a particular procedure, Enumerate will ignore any objects 
of that type. 

Each procedure has a stop return parameter; the enumeration will stop if stop ever has 
the value true. Some of the procedures also have a TextContainer handle as a parameter; 
the client can use this TextContainer recursively in other calls to Enumerate to obtain the 
contents of the TextContainer. 

The clientOata pointer passed in to Enumerate is passed to the callback procedures 
invoked by (that call to) Enumerate. (The clientOata may be different at different 
recursion levels, of course.) 

The handle (header, caption, etc.) supplied to the client in the call-back is readonly and is 
valid only during the call-back's invocation; the client is not reponsible for releasing this 
handle. It is possible for such a handle to be nil; a nil handle means that the corresponding 
object has no text content. 

Note that the enumeration does include the default paragraph and page format characters 
supplied with the TextContainer. Thus, when copying a document into a new document, 
the client should be careful to avoid copying the default paragraph and page format 
properties, since that would cause duplication. 

62.2.3.3 Close 

Close: PROC [docPtr: long pointer to Ooc]; 

When through with an enumeration, the client should call Close, which releases storage 
associated with the Ooc handle and sets the Doc handle to nil. 
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62.2.4 Errors 

Error: ERROR [why: ErrorCode]; 

ErrorCode: TYPE » machine dependent { 

containerFull(O), documentFull, readoniyOoc, outOfDiskSpace, outOfVM, 
objectlllegallnContainer, badParameter, unimpiemented, firstAvailable, 
lastAvaiiable(255)}; 

Any of the Append* procedures can raise an error, which can be one of the following types: 

containerFuil there is no more room to append to this container. 

documentFuii no more room in the document. 

readoniyOoc document opened in ReadOniy mode. 

outOf OiskSpace not enough disk space for the operation. 

outOf VM not enough virtual memory for the operation. 

object! I legal I nContainer attempted to add an object to a container that does not support 

that object type. 

badParameter one of the arguments specified was invalid in this context, 

unimpiemented this function is not supported 

62.2.3 FUl-in Order 

OocinterchangeOefs provides procedures to append, enumerate, and clear the fill-in order 
of fields and tables. 

AppendltemToFilllnOrder: PROC[ 
doc: Doc, 

filllnOrderltemName: xstring. Reader, 
itemType: FilllnOrderitemType]; 

doc is the document that contains the field or table. 

filtinOrderitemName is the name of the object being added to the flll-in order. 

FilllnOrderitemType: type ■ machine dependent { 
fieid(O), table, fIrstAvailable, lastAvailable(255)}; 

FilllnOrderitemType specifies the type of object that will be added to the flll-in order. 

EnumerateFilllnOrder: proc[ 
doc: Doc, 

proc: FilllnOrderProc, 
clientData: long pointers- nil]; 

FiillnOrderProc: type ■ proc( 
clientData: long pointer, 
filllnOrderltemName: xstnng. Reader, 
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itemType: FilllnOrderltemTypel 

RETURNS [stop: BOOL 4- FALSE]; 

proc is a call-back procedure that is invoked once for each object in the fiU-in order. The 
arguments passed into proc include the name of the enumerated object as well as its type. 
The FillinorderProc can return stop = TRUE to halt the enumeration. 

clientData is client defined data that is passed to proc 

CiearFiillnOrder: proc [doc: Doc]; 

Clear the fill-in order for the entire document. 



62.3 Usage/Examples 

Here is an example of both enumeration and creation. This program adds the command 
OocEx to the Attention Window. When called, this command checks to see if the current 
selection is a document If it is, then the program enumerates the contents of that 
document and copies the information into a new document. The time consuming process of 
copying the file is performed in the background by detaching the procedure PerformCopy. 

f 
I 

directory 



OocExampie: program imports OoclnterchangeOef s, ... a { 

~ CopyOata defines the handles and properties needed for each instance of the copy 
~ A record of this type is allocated from the system zone each time the CopyEx command 
~ is invoked; it is freed if an error occurs or when the copy completes. 
Copy OataHandle: TYPE « lon6 pointer to Copy Data; 
CopyOata: type ■ record [ 

SOurceOoc, targetOoc: 0ocinterchangeOefs.0oc 4-NIL, 

copyEnumProcs: Docint«rchangeOef$.EnumProcsRecord «-[], 

fontProps: Ooclnterchang«PropsO«fs.FontPropsRecord 4- 
Do«tnterchangePropsO«fs.nuilFontProps, 

paraProps: Do<interchang«Propso«fs.ParaPropsRecord 

OoclnterchangePropsOef s. nu 1 1 Pa raPfOps, 
pageProps: OoclnterchangePropsOefs.PagePropsRecord 4- 

OoclnterchangePropsOvfs.nuliPageProps, 
tabStops: TabStopsHandle <-NiL, 
backGroundSession: NSFil«. Session 4-NSFU«.nullSession, 
ignoreNewPar, ignorePFC: boolean true]; 

TabStopsHandie: type « long pointer to TabStops; 
TabStops: TYPE « record [ 

list: sequence length: cardinal of oocint«rchang«Propso«fs.TabStop]; 
zone: uncounted zone ■ Haap.systemZone; 
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- This is the command procedure. It first obtains a reference to the selected file 

- and then copies the contents of that document to a new document. The copy 

- occurs by forking a background procedure that runs in a separate NSFiie.Session 
MakeOoc: MenuOata.MenuProc ■ { 

-get reference to selected file 
OpenStatus : OoclnterchangeOefs-OpenStatUS ; 
iFS€lectjon.CanYouConvert(file] THEN { 

seiVaiue: s«i«ction.Vaiue <-Seiection.Convert[file]; 

docFileRef : NSFiie.Reference > loophole( 

sal Value, value, long pointer to NSFiie.Reference] t ; 

- allocate the data object from the system zone 
copyOata: CopyOataHandie zone.NEw(CopyOata {]]; 

-create a new session and open the source document in that session 
copyOata.backGroundSession MakeNewSessionG; 
[copyOata.sourceOoc, openStatus] *- 

0ocinterchangeOefs.0pen(docFileRef, copyOata.backGroundSession]; 

- if the input file is valid, fork a process to perform the copy 

IF openStatus ■ ok then Process.Oetach[FORK PerformCopyUopyOata]] 
else{ 

NSFiie.Logoff[copyOata.backGroundSession]; 

zone.FREE[@copyOata]; 

Us«rT«rminal.BlinkOisplay[]}; 

} 

ELSE UserT«rminai.BilnkOjsplay[]; 
}; ~ MakeOoc 

- create a new NSFiling session so that the copy can be performed in the background. 
MakeNewSession: PROc[]RETURNS(session: NSFiie.Session] a { 

user: Atom.ATOM Atom.MakeAtom(''CurrentUser"L]; 
prop: Atom.ATOM Atom.MakeAtom("'1dentityHandie"L]; 
identity: Atith.ldentityHandle » Atoni.GetProp[user, prop] t .value; 
session 4- NSFiie.Logon(identity]; 

}; 
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- Enumerate the source document in the background and append 

- its contents to a new document via call-back procs. When the 
-- enumeration is complete, place the new file on the desktop. 
PerformCopy: PROC(copyOata: CopyOataHandle] ■ { 

docFile: NSFUe.Handie; - handle for the new file 

refDoc, refDt: NSFihi.Reference; - refs used when placing file on desktop 

desktop: NSFii«.Handle; 

destSession: NSFite.Session; - session for destination file 
startStatus:Dodnt«rchang«o«fs.StartCreationStatus; 

Process.SetPriority{procMs. priority Background]; - execute in the background 

- initialize the enumeration call-back procs and retrieve the props 

- from the source document to be used in creating the detination doc. 
copyOata.copyEnumProcs InitEnumProcsQ; 
GetlnitialDocProps(copyOata.sourceOoc, copyOata] ; 
copyOata.paraProps.tabStops 4- 

iF copyOata.tabStops ■ nil then oescriptor[niu 0] 

ELSE OESCRiPT0R(@copyOata.tabStops.list(0l, copyOata.tabStops.length]; 

~ create the destination document using props obtained from the source doc 
[doc: copyOata.targetOoc, status: startStatus] 4-oocinterchangeo«fs.StartCreation[ 

paginateOption: simple, 

i niti a I FontProps : @copy Data, f ontProps, 

initialParaProps: @copyOata.paraProps, 

initiaiPageProps: @copyOata.pageProps]; 

- free data allocated for StartCreation 

IF copyOata.tabStops # nil then zone.FREE(@copyOata.tabStops]; 
iF StartStatus # ok then { 

Dodnt«rchangeo«fs.C!ose[@copyOata.sourceOoc]; 

NSFii«.Logoff(copyOata.backGroundSession]; 

zone.FREE[@copy Data] ; 

return}; 

~ enumerate the source document; copyOata will be passed to each call-back 
Q 4~0oclnt«rchange0efs.Enumerate[ 

[doc[h: copyOata.sourceOoc]], ©copyOata.copyEnumProcs, copyOata]; 

Oocinterchang«oefs.CIose(@copyOata.sourceOoc]; 

[docFile, destSession,] oocint«rchangeo«fs.FinishCreation[@copyOata.targetOoc]; 

- if no errors occurred when finishing creation, place new file on desktop. 
refOoc «~NSFii«.GetReference(docFile, destSession]; 

ref Dt *- starO«sktop.GeKurrentDesktopFiie(]; 

desktop 4- NSFii«.OpenByReference(reference: refOt, session: destSession]; 

NSF(ie.Move(file: docFile, destination: desktop, session: destSession]; 

NSFii«.Close(desktop, destSession]; 

NSFii«.CIose[docFile, destSession]; 

NSFne.Logoff[copyOata.backGroundSession]; 

NSFiie.Logoff [destSession] ; 

starDesktop.AddReferenceToOesktop[refDoc]; 

}; 
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-The call-back procs for enumeration just add the specified struaure to the new doc. 

- Add new paragraph to new document. If it is the first new paragraph 
~ character, then ignore it, since new document will already have one. 
AppendNewParToTargetOoc: oocinterchangeOefs.NewParagraphProc ■ { 

copyData: CopyOataHandle a clientOata; 

IF copyData JgnoreNewPar then copy Data. ignoreNewPar false 

ELSEOocinter€hangeO«fs.AppendNewParagraph[ 

[doc(h: copyOata.targetDoc]], paraProps. fontProps]; 

}; 

-Append page break to new document 

AppendPageBreakToTargetOoc: oocinterchangeOefs.PageBreakProc ■ { 
copyOata: CopyOataHandle ■ clientOata; 

Docinterchangeo«fs.AppendPageBreak(cQpyOata.targetOoc, fontProps]; 

}; 

- Add page format character to new document. If it is the first format 

- character, then ignore it, since new document will already have one. 
AppendPFCToTargetOoc: DodnterchangeO«fs.PFCProc » { 

copyOata: CopyOataHandle ■ clientOata; 

IF copyOata.ignorePFC then copyOata.ignorePFC *- false 

ELSE [] ir" OocinterchangeOefs.AppendPFCl 

to: copyOata.targetOoc, pageProps: pageProps, fontProps: fontProps]; 

}; 

-Append text to new document 

AppendTextToTargetOoc: OocmterchangeOefs.TextProc « { 
copyOata: CopyOataHandle ■ clientOata; 
OocinterchangeOef s. A ppe n dText( 

[doc[h: copyOata.targetOoc]], 

text. 

textEndContext, 
fontProps]; 

}; 

~ initialize the enumeration call-back procedures 
InitEnumProcs: PROCRETURNS[Docint«rchangeOefs.EnumProcsRecord] ■ { 
RETURN[[newParagraphProc: AppendNewParToTargetOoc, 

pageBreakProc: AppendPageBreakToTargetOoc, 

pfcProc: AppendPFCToTargetOoc, 

textProc: AppendTextToTargetOoc]]; 

}; 



Viewpoint Programmer's Manual 



62 



- These procedures obtain the properties for the first paragraph and PFC 

- charaaers in the source file and store the information in the data object. 

- Copy the font, para, and page props of source document by 

~ enumerating the first PFC and NewParagraph characters in the 

- source document and copying the properties to the data object. 

GetlnitiaiDocProps: PROc(sourceOoc: Oocint«rchang«o«fs.0oc,copy0ata : 
CopyOataHandle] a { 

tempEnumProcs: Oocint«rchangeo«f$.EnumProcsRecord [ 

newParagraphProc: FirstNewParProc, 

pfcProc: FlrstPFCProcl; 

[] Oocinterchan9eO«fs.Enumerate{ 

[doc[h: copyOata.sourceOoc]], ©tempEnumProcs, copy Data]; 

}; 



- save font, paragraph, and tab stop properties in 

- the data object then stop the enumeration. 
FirstNewParProc: oocinterchangeo«fs.NewParagraphProc ■ { 

copy Data: CopyOataHandle > ciientOata; 
copyOata.f ontProps f ontProps f ; 
copyOata.paraProps *- paraProps f ; 
IF paraProps.tabStops # nil then 

copyOata.tabStops «- CopyTabs{paraProps.tabStops]; 

>; 

- save page properties in data object 
FirstPFCProc: DoclnterchangeOafs.PFCProc ■ { 

copyOata: CopyOataHandle » ciientOata; 
copyOata.pageProps *- pageProps f ; 
return[true]; - return from enumeration 

}; 



- Copy the tabstop info into the data record 

Copy Tabs: PROC [tabs: Ooclnterchang«PropsO«fs.TabStOps] 

RETURNS[newTabs: TabStopsHandle] m { 

newTabs 4~ zone.NEw(TabStops[tabs.LENGTHn; 

FOR i: CARDINAL IN [0..tabS.LENGTH) 00 

newTabs(i] 4-tabs[i]; 

ENOLOOP; 

}; 

- Add command to attention menu. 
Init: PROC ■ { 

name: xstring.ReaderBody 4~xstring.FromSTRING("DocEx"L]; 
Attention.AddMenuitem[M«nuOata.Createltem[zone, @name, MakeOoc]] ; 

}; 



InitCl; 
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63.4 Index of Interface Items 



Item Page 

AbortCreation: proc 9 

AnchoredFrameType: type 5 

AnchoredFrameProc: TYPE 11 

AppendChar: proc 5 

AppendAnchoredFrame: proc 5 

Appended umnBreak: proc 5 

AppendField: proc 6 

AppendNewParagraph: proc 6 

AppendPageBreak: proc 6 

AppendPFC: proc 6 

AppendText: proc 7 

AppendTile: proc 7 

Caption: type 2 

CaptionObject: type 2 

Close: PROC 13 

CotumnBreakProc: TYPE 11 

Doc: TYPE 2 

OocObject: type 2 

Docum«nto«fs.CheckAbortProc: proc 8 

Enumerate: proc 10 

EnumProcs: TYPE 11 

EnumProcsRecord : type 11 

Field: type 2 

FieidObject: type 2 

FieidProc: TYPE 11 

FinishCreation: proc 8 

FinishCreationStatus: type 8 

FinlshCreationWithCheckAbortProc: proc 8 

Footing: type 3 

FootingObject: type 3 

GetFontPropsOefaults: proc 9 

GetPagePropsOefaults: proc 9 

GetParaPropsOefauits: proc 9 

GetPageNumberOeii miter: proc 9 

Heading: type 2 

IHeadingObject: type 2 

NewParagraphProc: TYPE 12 

NotAppended: error 13 

Open: proc 10 

OpenStatus: type 10 

PFCProcrTYPE 12 

PageBreakProc: TYPE 12 

PaginateOption: type 3 

ReieaseCaption: proc 7 

ReieaseFieid: proc 8 

ReleaseFooting: proc 8 



Item Page 

ReleaseHeading: proc 3 

ReleaseTile: proc 3 

SetCurrentParagrapiiProps: proc 9 

StartCreation: proc 3 

TextContainer: type 2 

TextProc: TYPE 12 

Tile: type 3 

TileObject: type 3 

TileProc: TYPE 12 
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63.1 Overview 

This interface contains procedures and data types used to describe the properties in 
documents; it is intended for use with OodnterchangeOefs, GraphicsinterchangeOefs, 
TableinterchangeOefs, and TextlnterchangeDefs. 

63.2 Interface Items 

63.2.1 Frame Properties 

The chief type in this section is the FramePropsRecord, which describes the properties of 
an anchored frame. 

FrameProps: TYPE ■ long pointer to FramePropsRecord; 

ReadonlyFrameProps: type ■ long pointer to readonly FramePropsRecord; 

FramePropsRecord: type ■ record [ 
isorderStyle: BorderStyie, 
borderThickness: cardinal, 
frameOims: FrameOims, 
fixedWidth, 
fixedHeight: bool, 
span: Span, 

verticaiAlignment: VerticaiAlignment, 

horizontal Alignment: Horizontal Alignment, 

topMarginHeight. 

bottomMarginHeight, 

leftMarginWidth, 

rightMarginWidth: cardinal, 

sparel: long cardinal]; 

BorderStyie: type a machine dependent { 

invisible(0),soiid, dashed, broicen, dotted, double, firstAvailable, lastAvailable(255)}; 



63-1 



DocinterchangePropsDefs 



isorderStyie specifies the characteristics of the lines that make up the frame border. 

borderThickness specifies the thickness of the frame border. This value is in units of 1/72 
inch. 

FrameOims: type ■ record [w, h: cardinal]; 

frameOims specifies the height and width of the frame. These dimensions are also in units 
of 1/72 inch, 

f ixedWidth and fixedHeight indicate whether the frame will expand when necessary. 

Span: type » machine dependent {partiaiColumn(O), 

fuiiCoiumn, partialPage, fullPage, firstAvailable, lastAvajlable(255)}; 

span specifies how much of the page the frame occupies. This is not currently in use. 

VerticaiAiignment: type ■ machine dependent { 

top(0), bottom, floating, firstAvai labia, iastAvailable(255)}; 

HorizontaiAllgnment: type ■ machine dependent { 

left(0), centered, right, floating, fIrstAvailabie, lastAvailabie(255)}; 

vertical and horizontalAlignment specify the alignment of the frame relative to the page. 

^^""^ topMarginHeight, bottomMarginHeight, leftMarginWidth, and rightMarginWidth are 

the margins of the frame, in units of 1/72 inch. 

all items marked as spare are for future use. 

83.2.2 Page Properties 

The chief type in this section is the PagePropsRecord, which describes the various 
properties that can be associated with a page in a ViewPoint document. 

PageProps: TYPE ■ long pointer to PagePropsRecord; 

ReadonlyPageProps: TYPE ■ long pointer to readonly PagePropsRecord; 

PagePropsRecord: TYPE ■ record ( 
pageOlms: PageOims, -layout 
topMarginHeight, 
bottomMarginHeight, 
leftMarginWidth, 
rightMarginWidth: cardinal, 
startingPageSide: PageSide, 
bindingMarginWidth: cardinal, 
nCoiumns: cardinal, - column structure 
balancedCotumns, unequaiCoiumnWidths: bool, 
columnSpacing: cardinal, 
coiumnWidths: CoiumnWidths, 
startingPageNumber: cardinal, -page numbering 



62-2 



Viewpoint Programmer's Manual 63 



pageNumberFormat: NumberFormat, 
restartPageNumbering: aoou 
startingLineNumber, - line numbering 
lineNumberlnterval: cardinau 
lineNumberFormat: NumberFormat, 
lineNumberLocation: LineNumberLocation, 
headingStartsOnThisPage, heading 
headingSameOnLeftRlgiitPages, 
footingStartsOnThisPage, - footing 
footingSameOnLeftRightPages: bool, 
sparel : long gkrdinal]; 

PageOims: TYPE ■ machine dependent record [w, h: cardinal]; 

PageSide: type « machine dependent { 

nil(O), left, right, firstAvailabie, lastAvailabie(255)}; 

pageOims are the width and height of the table, in units of 1/72 inch. topMarginHeight, 
bottomMarg in Height, leftMarginWidth, and rightMarginWidth describe the page 
margins; these values are also in units of 1/72 inch. startingPageSide indicates whether 
the £irst page of the document should be a left-hand page or a right-hand page; nil means 
that there is no diiTerence between the two. bindingMarginWidth is the width of the 
binding margin, if there is one. 

nColumns, balancedColumns, unequalColumnWidth, and columnSpacing determine 
column structure. nColumns is the number of columns; balancedColumns specifies 
whether the length of the column is equal to the length of the page. unequalColumnWidth 
indicates that the columns may have varying widths. coiumnSpacing is the amount of 
space between columns, in units of 1/72 inch. 

ColumnWidths: TYPE > long pointer to ColumnWidthsRecord; 

ColumnWIdthsRecord: type ■ record [ 
length: cardinal, 
sparel : long cardinal, 

widths: sequence maxLength: cardinal of ColumnWidthRecord]; 

ColumnWidthRecord: TYPE ■ record [ 
w: cardinal, 
sparel: LONG cardinal]; 

The ColumnWidthsRecord record contains the number of columns (length) and a sequence 
that contains the width of each column. Spare fields are included in both the record and 
each of the sequence elements. 

startingPageNumbers, pageNumberFormat, and restartPageNumbering describe the 
page numbering properties. startingPageNumber indicates the page number at which the 
numbering should start; restartPageNumbering specifies whether renumbering should 
restart for this page, or continue from where the last numbering left off. 
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NumberFormat: type ■ machine dependent { 

cardinai(O), lowerCaseLetter, upperCaseLetter, lowerCaseRoman, 
upperCaseRoman, firstAvaiiabie, lastAvailabie(255)}; 

pageNumberFormat specifies the format of the page number; currently only cardinal is 
implemented. 

LineNumberLocation: type ■ machine dependent { 

leftMargin(Oh rightMargin, outerMargin, bothMargins, ' 
firstAvailabieJastAvajlable(255)}; 

startingLineNumber, lineNumberinterval, lineNumberFormat, and lineNumberLocation 
are not currently implemented. 

The remaining properties describe headings and footings. headingStartsOnThisPage and 
footingStartsOnThisPage indicate whether the designated heading/footing should start on 
this page or the next; headingSameOnLeftRightPage and footingSameOnLeftRightPages 
specifies whether all pages have the same heading/footing, sparel is for future use. 

63.2.3 Field Properties 

The chief field property is the FieldPropsRecord, which describes the properties of a field. 

FieldProps: TYPE ■ long pointer to FieldPropsRecord; 

ReadonlyFieldProps: type « long pointer to readonly FieldPropsRecord; 

FieldPropsRecord: type ■ record [ 

language: Muiti National. Language, 

length: cardinal, 

required: bool, 

skiplf : SkiplfChoiceType, 

stopOnSkIp: bool, 

type: FieidChoiceType, 

filllnRuie, - changing fillinRule implies changing filllnRuleRuns 

description, 

format, 

name, 

range, 

skipifField: xstring.ReaderSody, 
fiilinRuleRuns: FontRuns, 
sparel : long cardinal]; 

language determines the format of date and amount fields. There are many formats, so 
you would have to check the format for each particular language. 

length is the length of the field, in characters. 

required indicates whether the user is required to fill in the field. If required is true, the 
user will not be able to use next or skip to advance to the next field until this field has a 
value. 
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SkiplfChokeType: type • machine dependent { 

empty(O), notEmpty, never, always, firstAvailable, iastAvaiiable(255)}; 

skipif defines the conditions under which the field can be skipped when the user presses 
the NEXT key. stopOnSkip specifies whether the skipping action should stop at this field or 
not. 

FieidChoiceType: type ■ machine dependent { 

any(O), text, amount, date, firstAvailable, iastAvailabie(255)}; 

type speciHes the type of data that can be in the field, any indicates that the field can 
contain any characters, including frames and other fields, text indicates that the field can 
contain only letters, digits, and symbols entered from the keyboard, amount indicates that 

the field can contain only numbers, spaces, and the following symbols: + *$,.(). date 

specifies that entries in the field can contain only a date. 

filllnRule defines the flll-in rule for this field. 

description is posted for each field entered with the next key when "prompt for fields " is 
invoked, format controls the format in which information is presented. For a type of text, 
this property defines a required pattern that must be matched. For a type of amount or 
date, this field controls the form in which the contents of the field are presented, 
regardless of how the user enters them. For a type of any, the format property is not used. 

name is the name of the field. If no name is provided, the field will automatically be 
named Fieldn, as in Fieldl, Field2, and so on. 

range defines a specific range of acceptable entries. 

skipif Field contains the name of the field that will appear in the property sheet Skip if 
field. 

flillnRuleRuns is an auxiliary data structure that the client can attach to the xstring.Reader 

that describes the flU-in rule for the field. A font run describes the subsequences of 
characters within a Reader that have the same font attributes. 



63.2.4 Font Properties 

The PropsRecord is the chief type in this Section. Section 63.2.4.1 describes the fontOesc 
field; section 63.2.4.2 describes the other fields in a FontProps Record. 

FontProps: type ■ long pointer to FontPropsRecord ; 

ReadonlyFontProps: TYPE « long pointer to readonly FontPropsRecord; 

FontPropsRecord: TYPE ■ record [ 
fontOesc: FontDescription, 
offset: integer, 

foregroundBackground: ForegroundBackground, 
nUnderiines: cardinal, 
strikeout: bool, 
placement: Placement, 
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toBeOeieted. 
revised: boou 
width: Width, 
sparel: long cardinal]; 



63.2.4.1 FontOescription 

FontDescription: TYPE ■ RECORD [ 
family: Family, 

designVariant: OesignVariant, 
posture: Posture, 
weight: Weight, 
pointSize: cardinal, 
serif ness: Serif ness, 
sparel: LONG cardinal]; 

Family: type a machine dependent { 

century(O), f rutiger(1 ), titan(2), pica(3), trojan(4), vintage<5), eiite(6), 
letterGothic(7), master(8), cubic(9), roman(10), scientific(1 1 ), gothic(1 2), 
bold(13), ocrB(14), spokesman(15), xeroxLogo(16), century Thin(1 7), 
scientificThin(18), heivetica(19), helveticaCondensed(20), optima(21), 
times<22), baskerviile(23), spartan(24), bodoni(25), palatino(26), 
caledonia(27), memphis(28), exceisior(29), oiympian(30), univers(31), 
univefsCondensed(32), trend(33), boxPS(34), terminai(35), ocrA(36), logo1(37), 
logo2(38), iogo3(39), geneva2(40), times2(41), square3(42), courier(43), 
futura<44), prestige(45), aLLetterGothic(46), centurySchoolBook(47), 
firstUnused(48), lastUnused(510), backstop(511)}; 

family is the font family. 

DesignVariant: type * machine dependent { 

null(O), roman, italic, firstAvailable. lastAvaiiabie(255)}; 

designVariant specifies whether the character is roman or italic, null is not currently a 
valid value. 

Posture: TYPE » machine dependent { 

null(O), upright, slanted, backslanted, firstAvailable, iastAvailable(255)}; 

posture indicates the. slant (stress) of the character, If any. null is not currently a valid 
value. 

Weight: type ■ machine dependent { 

null(O), ultraLight, extraLight, light, semiLight, medium, semlBoid, bold, 
extraBold, ultraBold, firstAvailable, lastAvailable(255)}; 

weight is the thickness of the character. 

pointSize is the size of the font. Note that this value must be in the subrange [0..1023]. 
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Serifness: TYPE ■ machine dependent { 

null(O), serif, sansSerif, firstAvailable, lastAvailable(255)}; 

serifness indicates whether or not the character has serifs, null is not currently a valid 
value. 

sparel is for future use. 

63.2.4.2 The other fields in FontProposRecord 

offset is the offset of the character from the baseline. 

ForegroundBacicground: TYPE ■ machine dependent { 

null(O), biackOnWhite, whiteOnBlack, firstAvailabie, iastAvajiabie(255)}; 

foregroundSackground indicates the color of the character relative to the display. 

nUnderiines indicates the number of times that the character is underlined; the value 
must be in the range [0..3]. 

strikeout indicates whether or not the character has been marked for deletion. 

Placement: type » machine dependent{ 

nuil(O), sub, subSub, subSuper, super, superSub, superSuper, userSpecif ied, 
firstAvailabie, lastAvaiiable(255)}; 

placement indicates the position of the character relative to the line. 

toBeOeieted indicates "normar text that has been marked for deletion in Redlining mode. 

revised indicates text that was typed in while Redlining was on but before finalizing the 
Redlined revisions. 

Width: type • machine dependent { 

proportionai(O), quarter, third, half, threeQuarters, full, firstAvailabie, 
lastAvailable(255)}; 

width is used for Japanees text and should be set to proportional to get normal characters. 
63.2.3 Font Runs 

FontRuns are used to associate font properties with text. XString provides no facilities for 
associating font properties with text; DoclnterchangePropsOefs allows the client to create 
font information structures that point into XString structures to make the association. 

The data structures in this section mark font runs, which are consecutive characters with 
the same font. A FontRunsRec describes the font, while a cardinal value describes where 
the font starts in the text. 

In addition, this interface allows the client to enumerate the font runs in a given XString 
body of text. 
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Run: TYPE a record! 

props: FontPropsRecord, 
index: cardinal, 
context: xstring.Context, 
sparel: LONG cardinal]; 

A Run indicates the beginning of a font run. props is the field describing the font used in 
the font run. index is the byte ofTset in the byte sequence that holds the text; it is the byte 
offset from the beginning of the byte sequence to the byte after the byte run. context is the 
XStrIng context describing the next byte run. The context of the first byte run is contained 
in the reader body. See the next section for further explanation. 

FontRuns: TYPE ■ long pointer to FontRunsRec; 

FontRunsRec: type ■ record { 
length: cardinal, 
sparel: long cardinal, 

runs: sequence maxLength: cardinal of Run]; 

FontRuns points to FontRunsRec, which is a record containing a sequence of Runs. 

EnumerateFontRuns: proc [ 
r: xstring. Reader, 
runs: FontRuns, 
proc: FontRunProc, 
ciientOata: long pointer nil] 
RETURNS [stopped: bool]; 

FontRunProc: type ■ proc ( 
r: xstring. Reader, 
fontProps: FontProps, 
ciientOata: long pointer] 
returns [stop: bool <- false]; 

EnumerateFontRuns allows you to perform some action for each font run in an 
xstring.Reader. FontRunProc is a call-back procedure that you pass to EnumerateFontRuns. 
If FontRunProc returns stopped • true, the enumeration stops and EnumerateFontRuns 
returns stopped ■ true. ciientOata is client defined data that you pass to 
EnumerateFontRuns, which passes it to FontRunProc every time FontRunProc is invoked. 



63.2.5.1 Meaning of Index and Context Fields in Run 

As stated earlier, index is the index into the XString of the byte following that run. 
context is the xstring.Context in effect after that run. Here are two examples: 

A ReaderBody with offset = 0, limit = 12, with bytes abcdefghijkl; font runs that describe 
the first three bytes as fontA, the next four as fontB, and the last five as fontC would be: 

fontRun 0: [props: fontA, index: 3, context: ...] 
fontRun 1 : [props: fontB, index: 7, context: ...] 
fontRun 2: [props: fontC index: 12, context: ...] 
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A ReaderBody with offset = 7, limit = 19, with bytes abcdefghijkl-, font runs that describe 
the first three bytes as fontA, the next four as fontB, and the last Qye as fontC would be: 

fontRun 0: [props: fontA, index: 10, context: ...] 
fontRun 1 : [props: fontB, index: 14, context: ...1 
fontRun 2: [props: fontC, index: 19, context: ...] 

63.2.6 Paragraph Properties 

The chief t3rpe in this section is the ParaPropsRecord, which describes the possible 
paragraph properties. 

ParaProps: type » long pointer to ParaPropsRecord; 

ReadoniyParaProps: type ■ long pointer to readonly ParaPropsRecord; 

ParaPropsRecord: TYPE > record [ 
basicProps: BasicPropsRecordt 
tabStops: TabStops, 
sparel : long cardinal]; 

basicProps describes all standard paragraph properties (those on the Paragraph property 
sheet); tabStops describes the current tab settings (the information on the Tab Settings 
property sheet). 

The following sections describe the BasicPropsRecord and TabStops records in detail. 



63.2.6.1 BasicPropsRecord 

BasicProps: TYPE ■ long pointer to BasicPropsRecord; 

Readonly BasicProps: type ■ long pointer to readonly BasicPropsRecord; 

BasicPropsRecord: TYPE ■ record [ 
preLeading, 
postLeading, 
leftlndent, 
rightlndent, 
lineHeight: cardinal, 
paraAlignment: ParaAiignment, 
justified, 
hyphenated, 

iceepWithNextPara: bool, 
language: MuitiNationaKLanguage, 
streakSuccession: StreakSuccession, 
defaultTabStopSpacing: DefaultTabStopSpacing, 
defauitTabStopAlignment: TabStopAlignment, 
sparel: LONG cardinal]; 

preLeadIng and postLeading are the spacing before and after the paragraph respectively; 
these values are in units of 1/72 inch. 
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leftindent and rightindent are the left and right paragraph margins; these values are in 
units of 1/72 inch. 

lineHeight is the default line height for the paragraph; this value is in units of 1/72 inch. 

ParaAlignment: type a machine dependent { 

left(0), center, right, firstAvailable, lastAvailabie(255)}; 

paraAiignment indicates the alignment of the paragraph relative to the containing text 
column or text block. 

justified when true, causes the text in the paragraph to stretch to make a straight right 
edge. 

hyphenated indicates whether the paragraph will be hypenated at the end of lines to 
improve justification. This parameter currently does nothing and should be set to false. 

IceepWithNextPara indicates whether the paragraph should always be on the same page 
as the succeeding paragraph. 

language is the language for the paragraph; this information is used for formatting 
decimal tabs. It is also used when items are added to the paragraph (e.g., a field inherits 
the paragraph language when added to the paragraph). 

StreaicSuccession: TYPE » machine dependent { 

ieftToRight(O), rightToLeft, firstAvailable, lastAvaiiable(2S5)}; 

strea ((Succession specifies whether a "streak" of characters should logically be read from 
left to right (e.g. English) or right to left (e.g. Hebrew). 

TabStopOffset: type * cardinal; 

OefauitTabStopSpacing: type ■ cardinal; 

defaultTabStopSpacing is the default number of spaces between tabs. 

TabStopAlignment: type ■ machine dependent { 

left(0), center, right, decimal, firstAvaiiable, iastAvaiiable(255)}; 

defauitTabStopAiignment is the default alignment for tabs: tabs can be relative to the left 
paragraph margin, the center of the paragraph, the right paragraph margin, or decimal 
points. 

sparel is for future use. 

63.2.6.2 Tabs 

TabStops: TYPE a long descriptor for array of TabStop; 

TabStop: type a record ( 
dotLeader: boolean. 
tabStopOffset: TabStopOffset. 
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tabStopAlignment: TabStopAiignment, 
sparel: LONG cardinal]; 

tabStops describes the currently set tabs for the paragraph. 

dotLeader indicates whether the tab has leader dots. tabStopOffset indicates the location 
of the tab, relative to the paragraph margin. tabStopAlignment indicates the alignment of 
the tab. 

nTabsMax: cardinal ■ 100; 

nTabsMax is the maximum number of tabs that there can be in a paragraph. 

63.2.7 Mode Properties 

Mode properties describe the commands in the document and auxiliary menus of a 
Viewpoint document. 

ModeProps: TYPE ■ long pointer to ModePropsRecord; 

ReadoniyModeProps: TYPE » long pointer to readonly ModePropsRecord; 

ModePropsRecord: TYPE ■ record [ 
structureShowing, 
nonPrintingShowing, 
coverSheetShowIng, 
promptFieids: bool, 
sparel : long cardinal]; 

structtureShowing, nonPrintingShowing, coverSheetShowing, and promptFieids specify 
the appearance of the displayed document. 

BooieanFalseOefault: type a bool^ false; 

ModeSeiections: type ■ packed array ModeElements of BooieanFalseOefault; 

ModeElements: type « { 

structureShowIng, nonPrintlngShowing, coverSheetShowing, promptFieids, 
sparel, spare2, spare3, spare4, spares, spare6, spare?, spares}; 

ModeSeiections are used to specify which ModeElements of a document should be acted 
upon. 

63.2.7 Constants 

The null*Props constants are declared so that clients may initialize property records 
with "neutral" properties. In most cases, each field value is the same as what would be set 
by the corresponding Get*PropsOefaults operation (sec 63.2.8). 

nuilFrameProps: FramePropsRecord a { 
borderStyle: solid, 
borderThicicness: 2, 
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frameDUns: [72. 721, 
fixedWidth: false, 
fixedHeight: false, 
span: partialColumn, 
verticaiAlignment: floating, 
horizontal Alignment: centered, 
topMarginHeight: 0, 
bottomMarginHeight: 0, 
leftMarginWldth: 0, 
rightMargin Width: 0, 
sparel : 01; 

nullPageProps: PagePropsRecord ■ [ 
pageOlms: [0, 0], 
topMarginHeight: 0, 
bottomMarginHeight: 0, 
leftMarginWldth: 0. 
rightMarginWidth: 0, 
startingPageSide: left, 
bindingMarginWidth: 0, 
nColumns: 1, 
balancedColumns: false, 
unequaiCoiumn Widths: false, 
coiumnSpacing: 0, 
coiumnWidths: nil. 
startingPageNumber: 1, 
pageNumberFormat: cardinal, 
restartPageNumbering: false, 
startingLineNumber: 1, 
lineNumberlnterval: 1, 
lineNumberFormat: cardinal, 
lineNumberLocation: leftMargin, 
headingStartsOnThisPage: true, 
headingSameOnLeftRlghtPages:TRUE, 
footingStartsOnThisPage: true, 
footingSameOnLeftRightPages:TRUE, 
sparel : 0]; 

nullCoiumn Width: ColumnWidthRecord ■ [ 
w: 0, 

sparel : 01; 

nuilFieldProps: FieldPropsRecord ■ [ 
language: USEnglish, 
length: 0, 
required: false, 
skiplf: never, 
stopOnSkip: false, 
type: any, 

filllnRuie: xstring.nullReaderBody, 
description: xstring.nullReaderBody, 
format: xstring.nullReaderBody, 
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name: xstring.nullReaderBody, 
range: xstring.nullReaderBody, 
skipif Field: xstring.nullReaderBody, 
filllnRuleRuns: nil, 
sparel : 0]; 

nullFontProps: FontPropsRecord a [ 
fontOesc: nullFontDescription, 
offset: 0, 

f oregroundBackground : biackOn White, 

nUnderilnes: 0, 

strikeout: false, 

placement: null, 

toBeOeleted: false, 

revised: false, 

width: proportional, 

sparel : 0]; 

nuilFontOescription: FontOescription ■ [ 
family: modern, 
designVariant: roman, 
posture: upright, 
weight: medium, 
points! ze: 12, 
serif ness: sansSerif, 
sparel: 0]; 

nullRun: Run a [ 

props: nullFontProps, 
index: 0, 

context: xstring.unknownContext, 
sparel: 0]; 

classic: Family ■ century; 

modern: Family ■ frutiger; 

nullParaProps: ParaPropsRecord « [ 
basicProps: nuilBasicProps, 
tabStops: oescriptor[nil, 0], 
sparel: 0]; 

nuilBasicProps: BasicPropsRecord a [ 

preLeading: 0, 
postLeading: 0, 
leftlndent: 0, 
rightlndent: 0, 
lineHeight: 12, 
paraAlignment: left, 
justified: false, 
hyphenated: false, 
keepWithNextPara: false. 
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language: USEnglish, 
streakSuccession: leftToRight, 
defaultTabStopSpacing: 18, 
defauitTabStopAlignment: left, 
sparel : 0]; 

nuilTabStop: TabStop ■ [ 
dotLeader: false, 
tabStopOffset: 0, 
tabStopAiignment: left, 
sparel : 0]; 

nullModeProps: ModePropsRecord » [ 
structureShowing: false, 
nonprinting Showing: false, 
coverSheetShowing: false, 
promptFieids: false, 
sparel : 0]; 

63.2.8 Default Properties 

i 

The Get*PropsDefauits procedures are called to obtain default values for property fields. 
These procediures differ from the constants in that they may obtain information from the 
'^^^ ^g^j. profile. Before calling any of these procedures, the client must declare a record of the 

appropriate type and pass its address to the Get*PropsOefaults procedure. None of these 
procedures allocate any additional data that the client would later have to free. 

GetFramePropsOefaults: proc [props: FrameProps]; 

GetPagePropsOefauits: proc [props: PageProps]; 

GetFieldPropsOefauits: proc [props: FieldProps]; 

GetFontPropsOefaults: proc [props: FontProps]; 

GetParaPropsOefaults: proc [props: ParaProps]; 

GetModePropsOefauits: proc [props: ModeProps]; 

GetPageNumberOelimiter: proc returns [xchar.Character]; 
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64.1 Overview 



GraphicsInterchangeDefs provides utilities for creating and enumerating the contents of 
anchored graphics frames. It is typically used in conjunction with OoclnterchangeOefs. 



64.1.1 Creating Graphics 



To create new graphics, the client starts by calling StartGraphics, which initializes a 
graphics frame so that information can be added to it. This procedure returns a Handle, 
which is a pointer to an opaque type that contains, among other things, a graphics 
container. A graphics container is just an object that can contain graphic objects: a 
graphics container can be an anchored graphics frame, a nested graphics frame, a cusp 
button within a graphics frame, or another similar construct, such as a chart. 

Once the client has a Handle, it can pass that Handle to various Add* routines to add new 
graphics objects, such as curves, rectangles, bitmaps, and text frames, to the graphics 
frame. 

The client can also add nested frames, such as non-anchored graphics frames, cusp 
buttons, or graphics clusters, to the anchored frame. To create these structures, the client 
should call StartGraphicsFrame, StartCuspButton, or StartOuster, respectively. Each of 
these procedures takes a graphics container as a parameter, and returns another graphics 
handle. The client can then use this as the graphics container in other calls to Add* 
routines. 

When everything has been added to a graphics container, the final step is to call a Finish* 
routine: FInishGraphics, FinishButton, FinishGraphicsFrame, or FinishCluster. 
FinishGraphics returns a graphics handle that can be passed to OoclnterchangeOefs. 

Thus, the scenario for creating a document with a floating graphics frame nested within 
am anchored graphics frame looks something like this: 

1. Call DoclnterchangaOefs.StartCreation to get a document handle (doc.) 

2. Call StartGraphics[docI to get an anchored frame handle (h). 



64-1 



64 



GraphicsInterchangeDefs 



3. Call Add'^th] to add graphics to the anchored frame. 

4. Call StartGraphicsFrame to get a handle for a nested graphics frame (gfh). 

5. Call Add*[gf h] to add graphics to the nested frame. 

6. Call FinishGrapicsFrameCgf h] to finish the nested frame. 

7. Call Finish<3raphics(h] to complete the anchored frame and get an object of type 
oocinterchang«oefs.lnstance (graphics). 

8. Call 0ocinterchangeOefs.AppendAnchoredFrame{graphjcs]. 

9. Call Do€lntarchangeOefs.FinishCreation{@dO€l. 



64.1.2 Reading Graphics 

GraphicsInterchangeDefs also includes the facilities to read the contents of graphics 
frames. To read a graphics frame, the client should call Enumerate. Enumerate takes as 
parameters a graphics container, and a record of call back procedures, one for each of the 
following graphics objects: {bitmap frame, cusp button, cluster, curve, ellipse, form field, 
frame, image, line, point, rectange, text, triangle, other}. 

Enumerate reads the contents of the graphics container, calling the appropriate procedure 
for each object that it encounters. If the client does not provide a procedure for a particular 
type of object, objects of that tjrpe will be ignored. Each of the client-supplied enumeration 
procedures can stop the enumeration if it so desires. 

There are similar procedures to enumerate the contents of cusp buttons. 
EnumerateButtonProgram takes a button program and a record to handle the various 
objects that can be in a button program: new paragraphs and text. 

64.2 Interface Items 



64.2.1 Creating graphics 

64.2.1.1 Start routines 

To create new graphics objects, the client must ^rst call StartGraphics to get an anchored 
frame handle. 

StartGraphics: proc[ 

doc: DocinterchangeOefs.Oocl 
RETURNS [h: Handle]; 

StartGraphics creates a new graphics frame within doc. 

Handle: TYPE a long pointer TO Object; 
Object: type; 
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There are also similar routines to create nested frames within a graphics container. 
StartOuster, StartGraphicsFrame, and StartButton each initialize a nested frame within a 
graphics container. Ail Start routines return a Handle, which the client can then pass to 
the various Add* routines to add graphics to that graphics container. 

StartCluster: PROC[h: Handle, box: Box] returns [ch: Handle]; 

StartCluster initializes a set of graphics objects in h. box describes the size and location of 
the cluster relative to the anchored frame; place and dims are in micas. 

Box: TYPE ■ RECORD [place: Place, dims: Dims]; « micas 

Place: TYPE ■ record [x,y: long integer]; 

Dims: type a record [w, h: long integer]; 

StartGraphicsFrame: proc[ 
h: Handle, 
box: Box, 

frameProps: ReadoniyFrameProps. 
name, description: xstring.Reader <— nil, 
spareProps: long pointer nil, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean false] 

RETURNS [ 

gfh: Handle, 

topCaption, bottomCaption, 

leftCaption, rightCaption: oocinterchang«o«fs.Caption]; 

StartGraphicsFrame initializes a nested graphics frame in h. box indicates the size and 
location of the nested frame relative to the graphics container; these values are in micas. 

frameProps are the properties for the frame. 

FrameProps: type » long pointer to FramePropsRec; 

ReadoniyFrameProps: TYPE ■ long pointer to readonly FramePropsRec; 

FramePropsRec: type ■ record [ 
brush: Brush, 
fixedShape: bool, 

margins: array Side of long cardinal, 

captionContent: array Side of DocinterchangeOefs.Caption, 

sparel: LONG cardinal]; 

Brush: TYPE * record [ 

wthbrush: long cardinal, 
stylebrush: StyleBrush]; 
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StyieBrush: type ■ machine oepenoent{ 

invisibie(O). solid(1), dashed(2), dotted(3), double(4), broken(5), (15)}; 

brush describes the properties of the lines that make up the frame. The brush width is in 
micas. The standard brush widths on the property sheet are 35, 71, 106, 141, 176 and 212. 

f ixedShape indicates whether the frame will expand in a uniform fashion. 

margins are the frame margins, in ppints. 

Side: type » {top, bottom, left, right}; 

captionContent is an array of captions associated with the frame. Note that the 
captionContent parameter is only meaningful during enumeration, and not during Start 
or Add* routines, since the caption content is added after the frame is created. 

sparel is for future use. 

name and description are the name and description of the graphics frame as it appears in 
the property sheet. 

spareProps is for future use. 

want*CaptionHandle indicates whether the client wants the frame to have the 
corresponding captions. If the client passes true for one of these values, the corresponding 
return value will be non-NiL. The client can then use OodnterchangeOefs routines to add 
text to the caption. Note that the caption must eventually be freed with 
Oo<lnterchangeOefs.ReleaseCaption. 

gf h is a handle to the newly created graphics frame. 

StartButton: proc[ 
h: Handle, 
box: Box, 

buttonProps: ReadoniyButtonProps, 
frameProps: ReadonlyFrameProps, 
wantProgramHandle, 
wantTopCaptionHandie. 
wantBottomCaptionHandle, 
wantLeftCaptionHandie, 
wantRightCaptionHandie: boolean false] 
returns [ 

bfh: Handle, 

buttonProgram: ButtonProgram, 
topCaption, bottomCaption, 

ieftCaption, rightCaption: oocintarchangeOefs.Caption]; 

StartButton initializes a cusp button as a graphics container, box describes the size and 
location of the cusp button relative to the graphics container h. 

ButtonProps: TYPE ■ long pointer To ButtonPropsRec; 
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ReadonlyButtonProps: type ■ long pointer to readonly ButtonPropsRec; 

ButtonPropsRec: type ■ record [ 
name: XString.Reader, 
sparel : long cardinal] ; 

ButtonProgram: type ■ long pointer to ButtonProgramObject; 

ButtonProgramObject: type; 

buttonProps are the default properties for the button. If the client defaults this parameter, 
StartButton will generate a new unique name for the button. 

wantProgramHandle specifies whether the client wants to be able to add to the button's 
program. If the client specifies true, and is returned a valid button program handle, then 
it must later free that handle with a call to ReieaseButtonProgram (see section 64.2.1.3). 
GraphicsinterchangeOefs provides several procedures that the client can use to add data 
to the cusp program; see section, Adding to a cusp button^ for information on these 
procedures. 

All other properties are as described for StartGraphicsFrame. 

64.2.1.2 Getting and Setting Frame Properties 

SetExtraAnchoredFrameProps: proc [ 
doc: Doclnterchang«0«fs.00C, 
anchoredFrame: oocinterchangeOefs.lnstance, 
name, description: xstring. Reader, 
spareProps: long pointer nil, 
selections: ExtraAnchoredFramePropsSelections]; 

ExtraAnchoredFramePropsSelections: type « packed array 

ExtraAnchoredFramePropsElements of Dodnter€hang«PropsD«fs.BooleanFalseOefault; 

ExtraAnchoredFramePropsEiements: type a {name, description, spareProps}; 

The client can associate a name and description with an anchored frame by calling 
SetExtraAnchoredFrameProps. doc is the document that contains the anchored frame. 
anchoredFrame is the frame in which the client intends to add a name or description. 
spareProps are for future use and should be left defaulted to nil. selections indicate which 
properties the client intends to add. 

GetExtraAnchoredFrameProps: proc [ 
doc: Doclnt«rchangeO«fs.0oc, 
anchoredFrame: DocinterchangeOafsJnstance, 
spareProps: long pointer *- nil, 
zone: uncounted zone] 

returns [name, description: xstring.ReaderBody]; 

The name and description properties can be retrieved from an anchored frame with 
GetExtraAnchoredFrameProps. spareProps and zone are for future use. The returned 
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values are not allocated from zone and so are read-only; the client should not attempt to 
call xstring.Fre€ReaderBytes on them. 

64.2.1.3 Adding information to a graphics container 

After calling a Start* routine to initialize a graphics container, the client will typically 
call various Add* routines to add information to the graphics container. The Add* 
routines defined below add an object to the end of the list of objects in the specified 
graphics container. 

The Add* routines are divided into two groups: geometries, and frames. The geometries 
section discusses how to add simple graphics objects: curves, ellipses, lines, points, 
rectangles, and triangles. The frames section describes how to add graphics objects in 
frames: bitmaps, form fields, images, and text frames. There is also a catch-all routine, 
AddOther, which provides the capability to add, as yet undefined graphics objects. 

There are also routines that add textual information to a cusp button program or to a text 
frame. These routines are at the end of the section. 

Geometries 

AddCurve: PROC[h: Handle, box: Box, curveProps: ReadoniyCurveProps]; 
CurveProps: TYPE ■ lon<3 pointer to CurvePropsRec; 



ReadoniyCurveProps: TYPE ■ long pointer to readonly CurvePropsRec; 
CurvePropsRec: type « record [ 

brush: Brush, 

llneEndNW: LineEnd, 

lineEndSE: LineEnd, 

lineEndHeadNW: LineEndHead, 

lineEndHeadSE; LineEndHead, 

direction: LineOlrection, 

placeNW, piaceApex, piaceSE, placePeak: Place, 

fixedAngle: bool, 

sparel: LONG cardinal]; 

LineEnd:TYPE » machine dependent { 

flush(O), square(1), round(2), arrow(3), (7)}; 

LineEndHead: TYPE ■ machine dependent { 
none(O), h1(1). h2(2), h3(3). (15)}; 

LineOlrection: TYPE ■ machine dependent { 
WE(0). NS(1 ), NwSe(2), SwNe(3)}; 



AddCurve adds the curve described by curveProps to the specified graphics container, box 
specifies the location of the curve relative to the graphics frame. If box. dims is smaller 
than the curve, only that part of the curve that fits within box. dims will be displayed. 
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brush indicates the line properties of the curve; brush is as described earlier for 
StartGraphicsFrame. 

lineEnd* describe the properties of the ends of the curve. lineEndNW describes the end that 
would paint first if the curve is traced clockwise; iineEndSE describes the end that would 
paint last tracing clockwise (Figure 64.1). 




Figure 64.1 Curve Direction 



If lineEnd = arrow, then lineEndHead describes the type of arrow: hi is the thinnest 
arrowhead; h3 is the thickest as shown in Figure 64.2. If lineEnd narrow, then 
lineEndHead should be none. 





h1 


► 


h2 


► 


h3 



Figure 64.2 Arrowheads 



direction is ignored; the client should always set this to WE. 

place* defines the curve by specifying its endpoints, apex, and peak. These points are 
relative to box, and not the frame itself. Recall that curves paint clockwise; clients must 
ensure that the NW endpoint appears before the SE endpoint when tracing the curve 
clockwise. Figure 64.3 illustrates these four points for two different curves; the triangle 
marks the apex, the square marks the peak, and the circles mark the endpoints. 
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Figure 64.3 Defining curves 



fixedAngie indicates that the curve will maintain its shape when grown or shrunk, sparel 
is for future use. 

AddEccentricCurve: proc[ 
h: Handle, 
box: Box, 

eccentri cCu rveProps : Readon iy EccentricCu rveProps] ; 

EccentricCurveProps: TYPE ■ long pointer to EccentricCurvePropsRec; 

ReadoniyEccentricCurveProps: type ■ 

LONG pointer TO READONLY EccentricCurvePfopsRec.' 

EccentricCurvePropsRec: type « record ( 
brush: Brush, 
lineEndNW: LineEnd, 
lineEndSE: LineEnd, 
lineEndHeadNW: LineEndHead, 
lineEndHeadSE: LineEndHead, 
direction: LineOirection, 
placeNW, placeApex, placeSE: Place, 
eccentricity: cardinal, 
fixedAngie: bool, 
sparel: LONG cardinal]; 

AddEccentricCurve is just like AddCurve except that the curve is specified by its 
endpoints, apex, and eccentricity, rather than by endpoints, apex and peak. 

eccentricity is a fraction represented by eccentricity / last{cardinal] . This allows the 
highest possible precision for eccentricities between 0 and 1. 

Add Ell ipse: proc[ 
h: Handle, 
box: Box, 

el 1 1 pseProps : Readon lyEi I i pseProps] ; 
EllipseProps: type ■ long pointer to ElllpsePropsRec; 
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ReadonlyEilipseProps: type ■ long pointer to readonly Ei I ipsePropsRec; 

EllipsePropsRec: TYPE a RECORD [ 
brush: Brush, 
shading: Shading, 
fixedShape: bool, 
sparel : long cardinal]; 

AddEllipse adds an ellipse to the specified graphics container, box.dims determine the size 
and shape of the ellipse; box.place determines its location relative to the frame h. 

Shading: type • record [gray: Gray, textures: Textures]; 

Gray: TYPE a machine dependent ( 

none(O), gray25(1), gray50(2), gray75(3), blacic(4), (1 5)}; 

Textures: TYPE a packed array Texture of boolean; 

Texture: type « machine dependent { 

vertical(O), horizontai(l), nwse(2), swne<3), polkadot(4), (11)}; 

Within the ElllpseProps, brush describes the ellipses' border, and shading describes its 
interior. The shading of the interior can be 25%, 50%, or 75% gray or solid black; the 
texture can be horizontal, vertical, or diagonal lines, or dots. fixedShape is the same for all 
"^mm^ shapes and indicates that the proportions of the object will not change when the user 

grows or shrinks it. sparel is for future use for all shapes. 

AddLine: PROC[ 
h: Handle, 
box: Box, 

lineProps: ReadoniyLineProps]; 

LineProps: TYPE ■ long pointer to LinePropsRec; 

ReadoniyLineProps: type • long pointer to readonly LinePropsRec; 

LinePropsRec: type ■ record [ 
brush: Brush, 
lineEndNW: LineEnd, 
lineEndSE: LineEnd, 
lineEndHeadNW: LineEndHead, 
lineEndHeadSE: LineEndHead, 
direction: LineOirection, 
fixedAngle: bool, 
sparel: LONG cardinal]; 

AddLine adds a line to the graphics container at location box.piace. LineProps are all as 
described above for curves. 

"^■•^ AddPoint: proc ( 

h: Handle, 
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box: Box, 

pointProps: ReadoniyPointProps]; 

PointProps: TYPE ■ long pointer to PointPropsRec; 

ReadoniyPointProps: TYPE « long pointer to readonly PointPropsRec; 

PointPropsRec: TYPE ■ record [ 
wthbrush: long cardinal, 
pointStyle: PointStyle, 
pointFiil: PointFill, 
sparel : long cardinal]; 

PointStyle: type ■ machine dependent {round(O), square<1), triangle(2), cross(3), (255)}; 

PointFiil: TYPE ■ machine dependent {sol id(0), hollow(1)« (255)}; 

AddPoint adds the point described by pointProps to the graphics container h at location 
box. place, wthbrush is in micas. pointStyle and pointFiil are as shown in the Point object 
property sheet. 

AddRectangie: proc[ 
h: Handle, 
box: Box, 

rectang leProps : ReadonI y Recta ng i eProps] ; 

RectangleProps: TYPE « long pointer to RectanglePropsRec; 

ReadoniyRectangleProps: type a long pointer to readonly RectanglePropsRec; 

RectanglePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading, 
fixedShape: bool. 
sparel: LONG cardinal]; 

AddRectangie adds the rectangle specified by box.dims to the graphics container at the 
location box.piace. Rectangle properties are as described above for ellipses. 

AddTriangie: PROC [ 
h: Handle, 
box: Box, 

triangleProps: ReadonlyTriangleProps]; 

TriangleProps: TYPE ■ long pointer to TrianglePropsRec; 

ReadonlyTriangleProps: type ■ 

LONG POINTER TO READONLY THanglePropsRec; 

TrianglePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading, 

placel, place2, placeS: Place, - corners of triangle 
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fixedShape: bool, 
sparel : long cardinal]; 

AddTriangie adds a triangle to the graphics conainter at location box.piace. brush and 
shading are as described for ellipses; piacel, piace2, and placeS are the corners of the 
triangle, relative to box. 

Frame objects 

The following Add* routines add various types of frame objects to the graphics container. 
Each of these routines has a parameter of type FrameProps that describes the frame, and 
want^CaptionHandle parameters that determine the captions for that frame. These 
parameters are as described in section 64.2.1.1, StartGraphicsFrame. 

AddBitmap: proc[ 
h: Handle, 
box: Box, 

bitmapProps: ReadonlyBitmapProps, 
frameProps: ReadoniyFrameProps, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean 4- false] 

RETURNS [ 

topCaption, bottomCaption, 

leftCaption, rightCaption: oodnterchangeOefs.Caption]; 

bitmapProps describes a bitmap frame. bitmapProps largely correspond to the properties 
that the user sees in the property sheet. 

BitmapProps: TYPE ■ long pointer to BitmapPropsRec; 

ReadonlyBitmapProps: type ■ long pointer to readonly BitmapPropsRec; 

BitmapPropsRec: TYPE ■ record [ 
opaque: boolean, 
xOff set, yOffset: long integer, 
printFile: xstring.ReaderBody, 
displaySource: BmOisplay, 
scalingProps: BItmapScalingProps, 
sparel : long cardinal]; 

opaque specifies whether the bitamp is opaque or transparent. xOffset and yOffset 
control the position of the bitmap within the bitmap frame. Setting both to 0 will position 
the bitmap flush in the upper left-hand corner. These values are in pixels. 

printFile is the source for the bitmap to print. This is usually the same as the display 
source, but the client may specify a file name as an alternate print source if desired. 

BmOisplay: TYPE a record! 
select ty pe :* prom 

internal ■ > [bm: long pointer to BitmapOata], 
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file a > [name: xstring. Reader Body ]« 
enocase]; 

The source for the displayed bitmap is in one of two locations: either internal (the bits are 
copied into the document), or in a file on the desktop. 

BitmapOata: TYPE a record [ 

signature: integer bmSignature, - do not use any other value 

xScale: lnterpress.Rational, 

yScale: Interpress.Rationai, 

xOim: cardinal, - # of bits wide 

yOim: cardinal, - # of bits tail 

bpl: CARDINAL, --Bits Per Line = ((xDim + 15)/ 16) * 16 

pages: NSS6gin«nt.PageCount, 

bits: PACKED ARRAY [0..0) OF Environment.Byte]; 
bmSignature: integer ■ 23456; 

The actual bitmap is described by a BitmapOata record, signature is a validity check for 
the bitmap. If a bitmap signature is anything but bmSignature, the implementation will 
not recognize it as a valid bitmap. 

xScaie and yScale specify the bitmap scale. At present, the only scale that is supported is 
72 spots per inch, so the client should always set xScale and yScaie to [254, 720,000]. ( The 
default unit for an interprass-Rationai is meters; converting inches to meters yields 720,000 
spots per 254 meters, since 1 inch = 2.54 cms.) 

xOim and yOim describe the size of the bitmap, bpl is the width of the bitmap, rounded to 
the nearest word boundary. The client should ensure that the bitmap's x dimension is 
equal to bpl. 

pages is the number of pages that the bitmap occupies, and bits is the actual bitmap. 

BitmapScaiingProps: type a record [ 
SELECT type: *from 

printerResolution » > [resolution: cardinal], 
fixed • > [ 

horizontal Alignment: {center, right, left}, 

verticalAiignment: {center, bottom, top}, 

scalingPercentage: cardinal [0..1024)], 
automatic ■ > [shape: {similar, filiUp}], 

other a > [sparel: packed array [2.. 15) of[0..1], spare2: cardinal], 
enocase]; 

scalingProps specifies one of the 3 bitmap scaling modes: automatic, fixed or 
printerResolution. The client will generally default the mode to automatic with shape a 
similar; this ensures that the bitmap will be automatically magnified/shrunk to fit just 
inside the bitmap frame until either the vertical or horizontal edge reaches the frame's 
edge. If fill Up is specified, the vertical and horizontal scaling factors are individually 
determined so that the bitmap completely fills the frame. 
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The fixed mode requires the client to control the bitmap's alignment (by Alignment 
parameters) and scaling (by Scale parameter). The scalingPercentage allows the client to 
shrink or magnify the bitmap. A scalingPercentage value of 100 means that the bitmap 
should be displayed and printed the same size as the original. A value of 50 means that the 
bitmap is shrunk to one half both vertically and horizontally. scalingPercentage must be 
in the range 1 - 1000. 

printerResolution indicates the resolution of the printer; typical values are: 72, 75, 150, 
200, and 300. Other values can be specified and must be the number of spots per inch. 

Add Form Field: proc[ 
h: Handle, 
box: Box, 

fieldProps: oocinterchangePropsOefs.ReadoniyFieldProps, 

frameProps: ReadonlyFrameProps, 

paraProps: oocinterchangePropsO€fs.ReadoniyParaProps nil, 

fontProps: oocinterchang«PrQpsOefs.ReadonlyFontProps «-nil, 

expandRight, expandBottom: bool false, 

wantFieldHandle, 

wantTopCaptionHandie, 

wantBottomCaptionHandle, 

wantLeftCaptionHandie, 

wantRightCaptionHandle: boolean 4~ false] 

RETURNS [ 

field: OoclnterchangeOefs.Field, 
topCaption, bottomCaption, 

leftCaption, rightCaption: oocinterchangeo«fs.Caption]; 
AddFormField adds the specified field to h at the location box. 

If the client specifies wantFieldHandle = true, AddFormField will return a 
OodntsrchangeOefs. Field; the client -must eventually free this field with a call to 
occinterchangeOefs.ReleaseFieid. To add information to the field, the client should use the 
facilities of DoclnterchangeOefs. 

Addlmage: proc[ 
h: Handle, 
box: Box, 

imageProps: ReadonlyimageProps, 
frameProps: Readonly FrameProps, 
wantTopCaptionHandie, 
wantBottomCaptionHandle, 
wantLeftCaptionHandie, 
wantRightCaptionHandle: boolean ^ false] 

RETURNS [ 

topCaption, bottomCaption, 

leftCaption, rightCaption: oocinterchangeOefs.Caption]; 
ImageProps: TYPE ■ long pointer to imageProps Rec; 
ReadonlyimageProps: TYPE ■ long pointer to readonly I magePropsRec; 
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ImagePropsRec: type ■ record! 
name: XString.Reader, 
sparel : long cardinal]; 



Addlmage adds an image frame to the specified graphics container. 

AddTextFrame: proc( 
h: Handle, 
box: Box, 

frameProps: Readonly FrameProps, 
textFrameProps: ReadonlyTextFramePropSt 
wantTextHandie, 
wantTopCaptionHandie, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRlghtCaptionHandie: boolean 4- false] 
returns [ 

text: T«xtlnterchangeOefs.Text, 

topCaption, bottomCaption, 

leftCaption, rightCaption: oocinterchange.Caption]; 

TextFrameProps: TYPE ■ long pointer to TextFramePropsRec; 

ReadonlyTextFrameProps: type > 

LONG pointer TO READONLY TextFramePropsRec; 

TextFramePropsRec: type ■ record ( 

expandRlght, expandBottom, transparent: bool, 
tFrameProps: Textinterchang«oefs.TFramePropsRec, 
sparel: long cardinal]; 

AddTextFrame adds a t:ext frame to the specified graphics container. If the client specifies 
wantTextHandle = true, it will return a handle to a text frame. 



Adding to a cusp button 

The following routines allow the client to add textual information to a cusp button 
program. 

AppendCharToButtonProgram: proc [ 
to: ButtonProgram, 
char: xchar.Character, 

fontProps: oocint«rchangePropso«fs.ReadoniyFontProps nil, 
nToAppend: cardinal 1]; 

Add a character to the button program. nToAppend is the number of copies of the 
character to be added; fontProps are the properties of the character. 

AppendNewParagraphToButtonProgram: proc [ 
to: ButtonProgram, 

paraProps: OodnterchangePropsDefs.ReadonlyParaProps <~nil. 
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fontProps: OocinterchangePropsOefs.ReadoniyFontProps 4- NIL, 
nToAppend: cardinal 4-1]; 

Add a new paragraph character with specified properties to the button program. 

AppendTextToButtonProgram: proc [ 
to: ButtonProgram, 
text: xstring.Reader, 
textEndContext: xstring.Context, 

fontProps: Docint«rchang«PropsDefs.ReadonlyFontProps 4- nil]; 

Add a string with specified properties to button program. For efHciency, the client should 
include textEndContext if known. 

Adding miscellaneous graphics 

AddOther: proc [ 
h: Handle, 
box: Box, 

i nstance : Docinterchangeoefs.1 nstance] ; 

AddOther is provided to allow addition of charts and other as yet undefined objects. For 
information on charts, see ChartOatainstailOefs. 

64.2.1.3 Release routines 

ReleaseButtonProgram: proc [ 

bpPtr: long POINTER TO ButtonProgram]; 

ReleaseButtonProgram releases the handles obtained from AddButtonProgram. Like 
Mesa's free operator, this routine take a pointer to the object to be freed, and sets the 
handle itself to nil. Thus, after a call to ReieaaieButtonProgram, ButtonProgram will be 

NIL. 

64.2.1.4 Finish routines 

When everything has been added to a graphics container, the client should call a Finish 
routine. 

FinishButton: proc [bfh: Handle]; 

FinishCluster: proc [ch: Handle]; 

FinishGraphks: proc [h: Handle] 

RETURNS [graphics: Ooclnterchange0efs.lnstance]; 

FinishGraphlcsFrame: PROC[gfh: Handle]; 

bfh, ch, h, and gfh are the handles obtained from the corresponding Start routines. The 
client will typically pass the Oocint«rchangeOefs.lnstance returned by FinishGraphics to 
DocinterchangeOefs.AppendAnchoredFrame. 
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64.2.2 Reading graphics 

To read the contents of a graphics frame, the client should call Enumerate. Enumerate 
takes as parameters a graphics container and a list of call back procedures, one for each of 
the kinds of items that might be in the graphics container. Enumerate will proceed 
through the graphics container, calling the appropriate procedure for each item that it 
encounters. 



Each enumeration procedure takes parameters that describe the properties of the object. 
These properties are temporary, and will be destroyed after the client procedure returns. 
If the client wishes to save any of these properties, it must explicitly copy them. 

Client EnumProcs do not need to call any Release* routines on anything passed them as a 
parameter. The Enumerator always releases containers after calling each EnumProc. 

In the case of a cusp button, cluster, or nested graphics frame, the client can recursively 
call Enumerate to get the contents of the nested frame. There are also related 
enumerators, TextinterchangeOefs.EnumerateText and EnumerateButtonProgram, that 
enumerate the contents of a text frame and a cusp button, respectively. 

Enumerate: proc[ 

doc: OocinterchangeOefs.Ooc, 
graphicsContainer: OocintarchangeOefs.lnstance, 

procs: EnumProcs. jm^ 
dientOata: long pointer <- nil] 
RETURNS [dataSkipped: boolean] ; 

EnumProcs: TYPE a long pointer to EnumProcsRecord; 



EnumProcsRecord: type ■ record ( 
bitmapProc: BitmapProc nil, 
buttonProc: ButtonProc nil, 
dusterProc: ClusterProc 4~nil, 
curveProc: CurveProc <-nil, 
ellipseProc: EllipseProc <-nil, 
formFieldProc: FormFleldProc <-nil, 
frameProc: FrameProc<-NiL, 
imageProc: ImageProc 4-nil, 
lineProc: LineProc <-nil, 
otherProc: OtherProc nil, 
pointProc: PointProc 4-NiL, 
rectangleProc: RectangleProc <~nil, 
textFrameProc: TextFrameProc *- nil, 
triangleProc: TriangieProc <~nil]; 

BitmapProc: type ■ proc [ 
clientData: long pointer, 
box: Box, 

bitmapProps: ReadoniyBitmapProps, 
frameProps: ReadonlyFrameProps] 

RETURNS [stop: BOOLEAN FALSE]; 
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ButtonProc: type ■ proc [ 
dientOata: long pointer, 
graphicsContainer:oocinterchan9eOefs.instance, 
box: Box, 

buttonProps: Readonly ButtonProps, 
frameProps: ReadonlyFrameProps, 
buttonProgram: ButtonProgram] 

RETURNS (stop: BOOLEAN 4- FALSE]; 

ClusterProc: type ■ proc [ 
dientOata: long pointer, 
graphi csContai ner : oocinterchangeoef s.i nsta nee, 
box: Box] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

CurveProc: type ■ proc [ 
dientOata: long pointer, 
box: Box, 

curveProps: ReadoniyCurveProps] 

RETURNS (stop: BOOLEAN 4- FALSE]; 

EllipseProc: type ■ proc( 
dientOata: LONG POINTER, 
box: Box, 

ell i pseProps : Readon I y El ii pseProps] 

RETURNS [stop: BOOLEAN *- FALSE]; 

FormFleidProc: type » proc [ 

dientOata: long pointer, box: Box, 

fieldProps: DoclnterchangePropsOefs.ReadoniyFleidPropS, 

frameProps: ReadonlyFrameProps, 

paraProps : oocinterchangePropso«fs.ReadonlyParaProps, 

fontProps: oocint«rchangePropso«fs.ReadonlyFontProps, 

expandRight, expandBottom: bool, 

content: oo<interchang«D«fs.Field] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

FrameProc: type ■ proc ( 
dientOata: long pointer, 

graphicsContainer: DodnterchangeOefs.lnstance, 
box: Box, 

frameProps: ReadonlyFrameProps, 
name, description: xstring.Reader, 
spareProps: long pointer] 

RETURNS (stop: BOOLEAN 4~ FALSE]; 

imageProc: TYPE ■ proc( 
dientOata: long pointer, 
box: Box, 

imageProps: ReadonlyimageProps, 
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frameProps: ReadoniyFrameProps] 

RETURNS [stop: BOOLEAN <- FALSE]; 

LineProc: type ■ proc [ 
dientOata: lon<3 pointer, 
box: Box, 

lineProps: Readonly Li neProps] 
RETURNS [stop: boolean false] ; 

OtherProc: type ■ proc ( 
ciientData: long pointer, 
box: Box, 

instance: OocinterchangeOefs.lnstance, 
objectType: OtherObjectType] 
returns [stop: boolean <- false]; 

OtherObjectType: type « machine dependent { 

iliusFrame(O), barciiart, linechart, piechart, plesllce, table, equation, 
firstAvailabie, lastAvailable(255)}; 

Pol ntProc: TYPE ■ proc[ 
clientOata: long pointer, 
box: Box, 

pointProps: ReadonlyPointProps] 
returns [stop: boolean false]; 

RectangieProc: TYPE ■ proc[ 
ciientData: long pointer, 
box: Box, 

rectangleProps: ReadonlyRectangieProps] 
returns [stop: boolean 4- false]; 

TextFrameProc: type ■ proc [ 
clientOata: long pointer, 
box: Box, 

frameProps: ReadoniyFrameProps, 
textFrameProps: ReadonlyTextFrameProps, 
content: TextlnterchangeOefs.Text] 
RETURNS [stop: BOOLEAN 4- FALSE]; 

TriangieProc: type ■ proc ( 
clientOata: long pointer, 
box: Box, 

triangleProps: ReadonlyTriangleProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

Enumerating button programs 

EnumerateButtonProgram: proc [ 
buttonProgram: ButtonProgram, 
procs: ButtonProgramEnumProcs, 
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dientOata: long pointers- nil] 
RETURNS [dataSkipped: boolean]; 

ButtonProgramEnumProcs: type ■ 

LONG POINTER TO ButtonProgramEnumProcsRecord; 

ButtonProgramEnumProcsRecord: type ■ record [ 

newParagraphProc: oocint«rchangeD«fs.NewParagraphProc *- nil, 
textProc: Oodnt«rchangeO«fs.TextProc <-nil]; 

EnumerateButtonProgram enumerates the contents of buttonProgram, calling the client- 
supplied procs as appropriate. ciientOata is passed to each of the call-back procedures 
during enumeration. 



64.2.3 Constants 

nullBitmapProps: BitmapPropsRec ■ [ 
opaque: true, 
xOffset: 0, 
yOffset: 0, 

pri ntFi ie : xstring. nul I ReaderBody , 
dispiaySource: nuilBmOisplay, 
scalingProps: nullBitmapScaiingProps, 
sparel : 0]; 

nuilBmOispiay: BmOisplay ■ [internai[bm: nil]]; 

nullBitmapScaiingProps: BitmapScaiingProps * [automatic[shape: similar]]; 

nullButtonProps: ButtonPropsRec « [name: nil, sparel: 0]; 

nullCurveProps: CurvePropsRec « [ 
brush: [0, solid], 
lineEndNW: flush, 
lineEndSE: flush, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
piaceNW: [0, 0], 
piaceApex: [0, 0], 
placeSE: [0, 0], 
piacePeak: [0, 0], 
fixedAngle: false, 
sparel : 0]; 

nuilEccentricCurveProps: EccentricCurvePropsRec » [ 
brush: [0, soiid]« 
lineEndNW: flush, 
lineEndSE: flush, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
placeNW: [0, 0], 
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piaceApex: [0, 0], 
piaceSE: [0, 0], 
eccentricity: 0, 
fixedAngie: false, 
sparel: 0]; 

nullEilipseProps: EilipsePropsRec ■ [ 
brush: [0, solid], 
shading: [none,Au[FALSE]]« 
fixedShape: false, 
sparel: 0]; 

nullFrameProps: FramePropsRec ■ [ 
brush: [0, solid], 
fixedShape: false, 
margins: all[0], 
captionContent: all[nil], 
sparel: 0]; 

nulllmageProps: ImagePropsRec ■ [name: nil, sparel: 0] ; 

nullLineProps: LinePropsRec ■ [ - 
brush: [0. solid], 
lineEndNW: flush, 
lineEndSE: flush, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
fixedAngie: false, 
sparel: 0]; 

nullPointProps: PointPropsRec ■ [ 
wthbrush: 0, 
pointStyie: round. 
pointFili: solid, 
sparel: 0]; 

nuilRectangieProps: RectanglePropsRec » [ 
brush: [0, solid], 
shading: [none, all[false]], 
fixedShape: false, 
sparel : 0]; 

nullTextFrameProps: TextFramePropsRec ■ [ 
expandRight: false, 
expandBottom: false, 
transparent: false, 

tFrameProps:TextinterchangeDefs.nullTFrameProps, 
sparel : 0]; 

nullTriangieProps: TrianglePropsRec ■ [ 
brush: [0, solid]. 



Viewpoint Programmer's Manual 



64 



shading: [none, all[false]]« 
placel : [0, 0], 
place2: [0, 0], 
places : [0, 0], 
fixedShape: false, 
sparel: 0]; 
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68.3 Index of Interface Items 



Item Page 

AddBitmap: proc 9 

AddCurve: proc 5 

AddEccentricCurve: proc 6 

AddEilipse: proc 7 

AddFormFieid: proc 10 

Addimage: PROC 11 

Add Line: proc 7 

AddOther: PROC 13 

AddPoint: proc 8 

AddRectangle: proc 8 

AddTextFrame: proc 12 

AddTriangJe: proc 8 

AppendCharToButtonProgram: proc 13 

AppendCharToText: PROC 12 

AppendFieidToText: proc 12 
AppendNewParagraphToButtonProgram: proc 13 

AppendNewParagraphToText: proc 12 

AppendTextToButtonProgram: PROC 13 

AppendTextToText: PROC 13 

BitmapOata: type 10 

BitmapProc: type « proc 1 5 

BitmapProps: type 9 

BitmapPropsRec: type 9 

BmOisplay: type 9 

bmSignature: integer 10 

Box: type 3 

Brush: type 3 

ButtonProc: TYPE 15 

ButtonProgram: type 4 

ButtonProgramEnumProcs: TYPE 17 

ButtonProgramEnumProcsRecord: type 17 

ButtonProgramObject: type 4 

ButtonProps: type 4 

ButtonPropsRec: type 4 

CiusterProc: type 15 

CurveProc: TYPE 15 

CurveProps: type 5 

CurvePropsRec: type 5 

Dims: type 3 

EccentricCurveProps: type 6 

EccentricCurvePropsRec: type 7 

EllipseProc: type 16 

EllipseProps: type 7 

EllipsePropsRec: type 7 

Enumerate: PROC 15 

EnumerateText: proc 17 

EnumerateButtonProgram: proc 17 



Item Page 

EnumProcs: type 1 5 

EnumProcsRecord: TYPE 15 

ErrorType: type 18 

Error: signal 18 

FieidChoiceType: type , 1 1 

FieldProps: type 11 

FieldPropsRecord: TYPE 11 

FinishButton: PROC 14 

FinishCluster: proc 14 

FinishGraphics: PROC 14 

FinishGraphicsFrame: proc 14 

FormFieldProc: TYPE 16 

FrameProc: TYPE 16 

FrameProps: type 3 

FramePropsRec: type 3 

Gray: type 7 

Handle: type 3 

ImageProc: TYPE 16 

I mageProps : type 1 2 

ImagePropsRec: TYPE 12 

LineDirection: type 5 

LineEnd: type 5 

LineEndHead: type 5 

LineProc: type 16 

LineProps: type 8 

LinePropsRec: type 8 

Object: type 3 

OtherProc: type 16 

Place: type 3 

PointFUl: TYPE 8 

PointProc: TYPE 16 

PointProps: type 8 

PointPropsRec: type 8 

PointStyie: type 8 

RectangieProc: TYPE ■ PROC 16 

RectangleProps: type 8 

RectanglePropsRec: type 8 

ReieaseButtonProgram: PROC 14 

ReleaseText: proc 14 

Shading: type 7 

Side: type 4 

SkiplfChoiceType: TYPE 11 

StartButton: proc 4 

StartCiuster: proc 3 

StartGraphlcs: proc 2 

StartGraphicsFrame: proc 3 

StyieBrush: type 4 
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Item 


Pace 


Text: TYPE 


12 


TextEnumProcs: type 


17 


TextEnumProcsRecord: type 


17 


TextFrameProc: type 


17 


TextObject: type 


12 


Texture: type 


7 


Textures: type 


7 


TriangleProc; type 


17 


TriangleProps: type 


8 


TriangiePropsRec: type 


9 
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65.1 Overview 

TablelnterchangeDefs allows clients to read the contents of a table, create a new table, or 
add information to an existing table. This interface should be used in conjunction with 
OoclnterchangeOefs. 

A table is described by three sets of properties: table properties, column properties, and 
row properties. Table properties include the name of the table, a description of table 
headers and the number of columns and rows in the table; column properties include 
whether the columns are divided, and the alignment of text within the columns; and row 
properties include information about how the text is aligned within a given row. The 
actual content of a table is included with the row information. 

65.1.1 Table building 

To create a new table, the client should start by calling StartTable. This procedure takes 
table properties and column properties as parameters, and returns a table handle. Handle 
points to Object, which is a record that contains, along with table-related data, a pointer to 
the actual table content (See section 65.2.1.1 Diagram of Table Structure, Fig. 65.2). 
Initially, the row properties have default values and the table has no content; the client 
should initialize row properties and content after the call to StartTable. 

To add content to the table, the client can pass the table handle to AppendRow, which 
adds new information to the table. When all of the rows have been added, the final step is 
to call FinishTable, which creates the final structure for the table. Once the table is 
created, the client can pass this table to the procedures in DoclnterchangeDefs to append 
it to a document. 

FinishTable returns an 0ocinterchangeOefs.lnstance for the table, which the client can pass to 
OocinterchangeOefs.AppendAnchoredFrame. 

To add information to an existing table, the client should call StartExistingTable instead of 
StartTable. This procedure also returns a table handle, which the client can then pass to 
AppendRow and FinishTable. StartExistingTable takes an Oodnterchangeoefs.lnstance as a 
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parameter; the client will typically call TabieS«i«ctionO«fs.TableFromSeiection to get the 
currently selected table as a value of type OodnterchangeOefs.lnstance. 



63.1.2 Table reading 

To read the contents of a table, the client typically starts by calling Enumerate. 
Enumerate takes as arguments a table object (oo€int«rchang«o«fs.lnstance) and a record of 
three call back procedures: a TabieProc, a CoiumnsProc, and a RowProc. 

Enumerate will call the TabieProc and the ColumnsProc once for a given table; these 
procedures obtain the table and column properties. Since the content of the table is stored 
with the rows. Enumerate will call the RowProc once for each row in the table. 

There is a also a procedure EnumerateSpecificRows, which is just like Enumerate except 
that it enumerates a specific list of rows within a table rather than the entire table. 
EnumerateSpecificRows will call the RowsProc once for each row in the specified range of 
rows. 



65.2 Interface Items 



65.2.1 Table building operations 

65.2.1.1 Creating a new table 

StartTable: proc [ 

doc: DocinterchangeO«fs.OOC, 
props: TableProps, 
c: Coiumnlnfo] 
RETURNS [h: Handle]; 

StartTable creates a document table in doc. props describes the properties of the table 
itself; c describes the properties of the columns. The Handle that is returned contains a 
description of row properties and table content. 

The following sections describe TableProps, Coiumnlnfo, and Handles in detail. 

StartTable can raise ErrorCdocumentFuill if the table and header row will not fit in the 
document. If StartTable raises this error, the table cannot be added to the document due to 
lack of space. 

Table properties 

A TablePropsRec describes the properties of a table and its headers. 

TableProps: TYPE « long pointer to TablePropsRec; 

TablePropsRec: type ■ record [ 
name: xstring.Reader, 
fllilnByRow, 
fixedRows, 
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fixedCoiumns: bool, 

numberOfColumns, 

numberOfRows: natural, 

visibleHeader, 

repeatHeader, 

repeatTopCaption, 

repeatBottomCaption: bool, 

borderline, 

dividerline: Line, 

horizontaiAiignment: Header Alignment, 
headerVerticaiAiignment: VerticaiAlignment, 
topHeaderMargin, bottomHeaderMargin: long cardinal, 
sortKeys: SortKeys, 
sparel : long cardinal]; 

name is the name of the table. 

fillinByRow determines what happens when the user presses the next key. If fiiilnByRow 

is TRUE, pressing the next key advances through the table one row at a time, and the table 
is expanded by rows. In this case, the number of columns is fixed and the number of rows 
can be either fixed or varying. If fillinByRow is false, then pressing the next key advances 
through the table one column at a time, and the table is expanded by columns. In this case, 
the number of rows is fixed and the number of columns can be either fixed or varying. 
fixedRows and fixedCoiumns indicate whether the user can change the number of rows 
and columns in the table. 

numberOfColumns and numberOfRows are used as hints for StartTable. 

visibleHeader indicates whether there should be a visible header at the top of the table; 
repeatHeader, repeatTopCaption, repeatBottomCaption indicates whether or not to 
repeat these items on every page if the table occupies multiple pages. 

borderLine describes the table border (not the frame border), and dividerLine describes the 
line between the header row and the rest of the table. In tables, a line is either solid or 
invisible; a solid line can have a width anywhere from one pixel to six pixels. 

Line: type a record [ 
iinestyle: Linestyie, 
linewidth: Linewidth]; 

Linestyie: type « machine depenoent{ 

none(O), solid, dashed, dotted, double, broken, firstAvailable,iastAvaiiabie(255)}; 

Linewidth: type ■ machine dependent {w1(0), w2(1), w3(2), w4(3), w5(4), w6(5)}; 

horizontaiAiignment and headerVerticaiAiignment specify the alignment of the text 
within a header. 

Header Alignment: type ■ HorizontaiAiignment [left..right]; 

HorizontaiAiignment: type ■ machine OEPENOENT{left(0),center(1),rlght(2),decimal(3)}; 
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VerticaiAiignment: type ■ machine dependent {fiushtop(O), centered(1),f iushbottom(2)}; 

topHeaderMargin and bottomHeaderMargin specify the amount of white space that 
should appear between above and below each header element. 

SortKeys: type ■ long pointer to SortKeysRec; 

SortKeysRec: type ■ record [ 
length: cardinal, 
sparel : long cardinal, 

keys: sequence maxLength: cardinal of SortKey]; 

SortKey: type « record { 

coiumnName: xsuing.Reader, 
sortOrder: xstring.SortOrder, 
ascending: bool, 
sparel: LONG cardinal]; 

The SortKeysRec contains a sequence of optional SortKeys for a table or column. A column 
must be divided-repeating in order to have sort keys. Each SortKey contains the column's 
name, its sortOrder and whether to sort in ascending or descending order. Sparel is for 
future use. 



V, Column properties 

Coiumnlnfo: type « long pointer to Col umnlnfoSeq; 

CoiumninfoSeq: type > record {sequence length: cardinal of Col umninfoRec]; 

ColumninfoRec: type » record [ 

headerEntryRec: HeaderEntryRec, 
name, descri ption : xstring. Reader, 
divided: bool, 
suiKolumns: natural, 
repeating: bool, 
subcolumninfo: Coiumnlnfo, 
alignment: HorlzontalAlignment, 

tabOffset, ~ Micas! (different from oo<int«rchangePropsD«f$.TabStop) 

width, 

leftMargin, 

rightMargin: long cardinal, 
type:oodntttrchang«PropsOefs.FieldChoiceType, 
required: bool, 

language: MuitiNationai.Language, 
format: xstring. Reader, 
stopOnSkip: bool, 
range: xstnng.Reader, 
length: cardinal, 
^^ap»^ skipText: xstring.Reader, 

skipChoice: Oo€interchangePropsDefs.SkiplfChoiceType, 
fillin: xstring.Reader, 

f i 1 1 i n Runs : OoclnterchangePropsOef s. FontRu ns. 
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line: Line. 

sortKeys: SortKeys, 
sparel : long cardinal] ; 

A ColumnlnfoSeq describes all the columns of a table; a ColumninfoRec describes one 
column in detail. Within a ColumninfoRec, the most complicated field is a 
header Entry Rec, all of the other fields correspond directly to the fields on the property 
sheet that the user sees. The next section, discusses the header properties; and the section. 
Other column properties, discusses the remaining column properties. 

For a more complete description of any of these properties, see the user documentation. 

Column header properties 

HeaderEntryRec: type ■ record [ 
subHeaders: HeaderlnfOr 
line: Line, 

singleLineHint: bool, 

sparel: LONG CARDINAL, 

content: EntryContent]; 

A HeaderEntryRec describes the textual content of a column header. Header text can 
contain only one font and one set of paragraph properties per column header. 

subheader describes the headers for each of the subcolumns. This field is only interesting 
if the column is divided. subHeader points to a sequence that contains a HeaderEntryRec 
for each subcolumn. Each subcolumn may in turn be suixiivided, in which case that 
subcolumn's HeaderEntryRec subHeader field would point to another sequence. 

Headerinfo: TYPE ■ long pointer to HeaderlnfoSeq; 

HeaderlnfoSeq: type ■ record [sequence length: cardinal of HeaderEntryRec]; 

line describes the properties of line that divides the header from subheaders; line is only 
visible If the column is subdivided. 

SingleLineHint is a hint that the header only contains one line of text; this makes the code 
slightly faster by simplifying the calculation of header size. 

sparel is for future use. 

EntryContent: type « record [ 
select mode: * from 

read « > [obtainTextProc: ObtainTextProc, obtainTextData: ObtainTextData], 
write « > [filllnTextProc: FilllnTextProc<-NiL,clientData: long pointer 4- nil], 
enocase]; 

ObtainTextData: type [4]; 

ObtainTextProc: type ■ proc [obtainTextData: ObtainTextData] 
RETURNS [text: TextlnterchangeOefs.Text]; 
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Table 



HeaderEntryRec for table : 



subHeaders 
"table" 
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Figure 65. 1 Table and HeaderEntryRec for table 
FilllnTextProc: TYPE ■ PROC[text:T«xtinterchang«o«fs.Text,dientOata: long pointer]; 



content is a varaint record that describes the content for a header entry. When 
enumerating a table, all the header entries will be of the form [read(...]]. The client may 
call the ObtainTextProc for an entry to obtain a TextinterchangeOefs.Text object, which may 
then be enumerated via T«xtlnterchangeOefs.EnumerateText. 

When creating a table, the client must set all header entries to [write{...]]. The client may 
set the fiiilnTextProc to a proc to be called back to fill in the entry with text. ciientOata will 
be passed to the client's fiiilnTextProc. The client may default the fiiilnTextProc to nil so 
that the entry will be empty. 



Other column properties 



name and description are the name and description of the table as it appears in the 
property sheet. 

divided specifies whether the columns can be divided, subcolumns is the number of 
subcolumns; repeating indicates that subcolumns can have subrows, and subcolumninfo 
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is the recursive description of the subcolumns. subcolumns, repeating, and 
subcolumnlnfo are ignored if divided = false. 

alignment describes the alignment of the text within a column. 

tabOffset specifies where the tabs should be set, relative to the margin. tabOffset only 
applies if alignment s decimal; it is in micas. 

width is the width of the column; leftMargin and rightMargin are the margins for the 
column. These values are also in micas. 

type indicates the type of content that will appear in a column. 

required indicates that the entry is required, and that the user must fill it in before 
proceeding to another entry in the table. 

language affects the format of date and amount fields. It is used when items are added to 
the paragraph (e.g., a field inherits the paragraph language when added to the 
paragraph). 

format allows the user to define a format to which the data in the table must conform. 

stopOnSkip When the user presses skip, the skipping action shoudl stop at the entry that 
has this option. 

range is used to define a specific range of acceptable entries. Once defined, any entry not 
within the defined range is not acceptable. See the user documentation for information on 
how ranges are defined. 

length allows the user to define the maxiumum number of characters that will be accepted 
in the column entries. 

skipText and skipChoice defines the conditions under which an area may be skipped when 
the user presses next. See the user documentation for more detail. 

fillin and f illinRuns describe the fill-in rules for completing the table. 

line describes the properties of vertical line to right of column. 

sortKeys describes the optional sort keys for the column. 

sparel is for future use. 

Return values 

StartTable returns a handle: 

Handle: TYPE ■ long pointer to Object; ' 

Object: type ■ record [ 

zone: UNCOUNTED ZONE, 

table: OocinterchangeOefs.lnstance, 

tableHeight: LONG CARDINAL, 
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table Width: long cardinal, 
rc: RowContent, 

Sparel: LONG CARDINAL, 

private: array [0..0) of word]; 



zone is the zone from which dynamic storage specific to this operation is allocated, table 
is the table itself. 

tableHeight is initially equal to the height of the header row and is updated after each call 
to AppendRow. tabieHeight and tabieWidth are in micas, rc points to a record used as 
temporary storage for a new row. 

RowContent: type ■ long pointer to RowContentSeq; 

RowContentSeq: type * record ( 

topMargin, bottom Margin: long cardinal 4- 0, 
line: Line [solid, w21, 

verticalAlignment: VerticalAlignment flushtop, 
sparel : long cardinal 0, 

rowdata: sequence length: cardinal of RowEntryRecj; 

RowContentSeq describes row properties and content. The margins are the row margins; 
line is the properties of the line separating the rows. verticalAlignment specifies the 
alignment of text within a row. sparel is for future use. rowdata describes the content. 

RowEntryRec: type ■ record [ 
subRows: SubRows, 
singleLineHint: bool, 
sparel : long cardinal, 
content: EntryContent]; 

A RowEntryRec describes the textual content of a given row entry. 

SubRows: TYPE ■ long pointer to SubRowsRec; 

SubRowsRec: type « record [ 
length: cardinal, 
sparel : long cardinal 0, 

rows: sequence maxLength: cardinal of RowContent]; 

SubRowsRec describes subrow properties and content. If subRows is non-NiL, then the rest 
of the RowEntryRec record is unused, since the information will be in the individual 
subrow records. 



Note that subrows may only exist if the parent column is divided. 
The remaining fields are as described for header properties. 



65.2.1.2 Opening an existing table 

StartExistingTabie: proc[ 

table: DoctnterchangeOefs.lnstance, 
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hi: Headerlnfo<-Niu 
rowPropsSource: natural 4-0, 
deieteExistingRows: book- true, 
numiserOf RowsHint: natural 0] 
RETURNS [h: Handle]; 

StartExistingTable sets things up to append rows to an existing table, table is the table 
object. The table passed in to StartExistingTable is often obtained from a call to 
TableS«ie<tionOefs.TabieFromSelection, which returns the current selection as a table. 



hi describes the desired properties for the table headers. If hi = nil then the existing 
column headers are used. 

rowPropsSource is the index of a row in the table; this is the row from which the default 
properties should be taken; the rows are numbered from [0..n].The horizontal alignment 
for each entry is taken from first new paragraph character in corresponding element of 
first row. 



deieteExistingRows indicates whether the implementation should delete the existing 
contents of the table before adding new information. numberOfRowsHint is a hint about 
the number of rows that the table will contain; this is for efficiency purposes. 

Like StartTable, StartExistingTable returns a Handle, which the client can then pass to 
AppendRow. 

This procedure will raise Error[tableNotEditable] if the document is read-only. 



65.2.1.3 Appending rows 

AppendRow: pR0c[h: Handle, rc: RowContent]; 

AppendRow adds the row described by rc to the table described by h. Typically, h will be a 
handle obtained from either StartTabie or StartExistingTable. 

RowContent is as described in section 65.2.1.1, return values for StartTabie. 

66.2.1.4 Finishing a table 

FinishTabie: pR0C[h: Handle] 

RETURNS [ 

table: Do<lnterchangeO«f$.lnstance, 
tableWldth, tableHeight: long cardinal]; 

The client should call FinishTabie when it is through editing a table. The table that is 
returned is intended to be passed as the content argument to 
DocinterchangeO«fs.AppendFriame. This operation deletes h.zone. tableWidth and 
tableHeight are in micas. 
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63.2.1.5 Miscellaneous utilities 

MaxTableEiements: proc returns [natural]; 

This procedure returns the maximum size of the table, allowing clients to be smarter 
about large tables. 

OefauitFontProps: proc [font: Oocint«rchangePropsO«fs.FontProps]; 
OefaultParaProps: proc [para: oocinterchangePropsOefs.ParaProps]; 

These procedures take a properties record and fill in reasonable default values. 

GetTablePropsFromName: proc( 
doc: Ooclnterchange0ef$.0oc, 
tableName: xstring.Reader, 
tableProps: TabieProps, 
zone: uncounted zone]; 

doc is the document from which to retrieve the properties of the table specified by 
tableName. 

tabieProps.name will be NiLbut the remainder of tableProps will contain the table's 
properties. 

If tableProps.sortKeys is not nil, it will be allocated from zone. 
66.2.2 Table reading operations 



EnumerateTabie: proc [ 

table: DocinterchangeO«fs.lnstance, 

procs: EnumProcs, 
cllentData: long pointer <- nil]; 



EnumProcs: type ■ long pointer to EnumProcsRec; 



EnumProcsRec: type ■ record [ 
tableProc: TableProc 4-nil. 
columnsProc: ColumnsProc 4~nil, 
rowProc: RowProc <-nil]; 



To parse the contents of a table, clients call Enumerate or EnumerateSpecificRows. 
Enumerate takes as parameters a table handle and a record of callback procedures: one for 
table properties, one for column properties, and one for row properties. 

TableProc: type ■ proc [ 
cllentData: long pointer, 
props: TableProps] 

RETURNS [stop: BOOL 4- FALSE]; 

ColumnsProc: type ■ proc[ 
cllentData: long pointer. 
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columns: Cotumnlnfo] 
RETURNS [stop: BOOL 4- false]; 

RowProc: type « proc [ 
ciientData: LONG POINTER, 
content: RowContent] 

RETURNS [stop: BOOL FALSE]; 

Enumerate calls the TableProc and the ColumsnProc once, passing in the appropriate 
property information. Because the content of the table is stored with the rows, Enumerate 
calls the rowProc once for each row in the table. 

Each of these callback procedures has a boolean return value. If stop is ever true, then the 
enumeration will stop. 

EnumerateSpecificRows: PR0C[ 
tr: TabteRows, 
procs: EnumProcs, 
dientOata: long pointer nil]; 

TableRows: TYPE ■ record ( 

table, firstRow, lastRow: DcwintarchangeDefsJnstance]; 

EnumerateSpecificRows describes a certain subset of rows in a table. As with Enumerate, 
the tableProc and the columnsProc will each be called once to describe the appropriate 
properties; the column information will describe the columns intersecting the described 
rows. The RowProc will be called once for each row in [firstRow.JastRow]. 

tabieRowsNIi: TableRows a [ 
Oo€lnterchangeO«f s. i nsta nce Nil, 
DoclnterchangeOef s. i nsta nceNl I , 
DoclnterchangeOefs.inStanceNil]; 

tableRowsNII specifies a default for TableRows. tableRowsNil is what you get if a table is 
not selected in a call to EnumericSpecif IcRows. 

65.2.3 Diagram of table structure 

Figure 65.2 is a diagram of a table structure. RowContent is a pointer to RowContentSeq; 
table is a record that contains two pointers to the actual instance of the table. (Note that 
table itself is not a pointer.) 

65.2.4 Constants 

The following constants can be used to initialize the various table properties to reasonable 
default values. 

nullLlne: Line ■ [linestyle: solid, linewidth: w1]; 

nuilSortKey: SortKey a [ 
columnName: nil, 
sortOrder: standard. 
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Figure 65.2 Diagram of Table Structure 



ascending: true, 
sparel : 0]; 

nullColumninfo: CoiumnlnfoRec ■ [ 
headerEntryRec: nullHeaderEntry, 
name: nil, 
description: nil, 
divided: false, 
subcolumns: 0, 
repeating: false, 
subcoiumninfo: nil, 
alignment: center, 
tabOffset: 0, 
width: 2540, 
leftMargin: 0, 
riglitlVlargin: 0, 
type: any. 
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required: false, 
language: USEnglish, 
format: nil, 
stopOnSkip: FALSE, 
range: nil, 
length: 0, 
skipText: nil, 
skipChoice: empty, 
fiilin: NIL, 
fililnRuns: nil, 
line: [solid, w2], 
sortKeys: nil, 
sparel: 0]; 

nuilHeaderEntry: HeaderEntryRec ■ [ 
subHeaders: nil, 
line: [solid, w21, 
singleLineHint: false, 
sparel: 0, 
content: [write[]]l; 

nuilRowEntry: RowEntryRec a [ 
subRows: nil, 
SingleLineHint: false, 
sparel : 0, 
content: [write{]]]; 

nuilTableProps: TablePropsRec ■ [ 
name: nil, 
fiilinByRow: true, 
fixedRows: false, 
fixedCoiumns: true, 
numberOf Columns: 0, 
numberOfRows: 0, 
visibleHeader: true, 
repeatHeader: true, 
repeatTopCaption: true, 
repeatBottomCaption: true, 
borderLine: [none, w1], 
dividerLine: [solid, w4], 
horizontalAlignment: center, 
headerVertical Alignment: centered, 
topHeaderMargin: 0, 
bottomHeaderMargin: 0, 
sortKeys: nil, 
sparel :0]; 

65.2.5 Errors 

TableError: signal [type: ErrorType]; 
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ErrorType: TYPE » machine dependent{ 

tabieTooWide, tableTooTail, tableHeaderTooTall, firstAvaiiable, lastAvajiabie<255)}; 

tableTooWide StartTable will raise this error if the specified table is too 

wide to fit in the document. 

tableTooTall AppendRow will raise this error if the specified table is too 

tail to fit in the document. 

tabieHeaderTooTali StartTable will raise this error if the specified headers are too tall. 

65.3 Usage/Examples 

Here is an example of a basic program that runs from the Attention Menu. It registers two 
commands: Make Table, which creates a new document with a table, and Add To Table, 
which adds four new rows to the selected table. 

DIRECTORY 



TableExampie: program 

iMPORTsTabieinterchangeOefs, TabieSeiectionOefs, TextlnterchangeDefs, ... a { 



tabieWidth: cardinal ■ 1600; -micas 

headerMargin: cardinal ■ 35 * 9; -micas; margin should be 9 pixels 
rowMargin: cardinal ■ 100; 

<<Menu Proc for Create Table command. Creates new document, creates new table, 
appends table to document, and then adds document to desktop. > > 
MakeOocument: ManuOata.MenuProc ■ { 
rows, columns: cardinal 4- 3; - arbitrary 
doc: OocinterchangeOefs.Ooc 4-oocinterchangeo«fs.StartCreation[ 

paginateOption: none].doc; 
table: oocinterchangeO«fsJnstance ■ BuildSimpieTable{doc, rows* columns]; 
props: oo<interchangePropso«fs.FramePropsRecord 4- 

oodnt«rchang«Propso«fs.nullFrameProps; 
props.frameOims [tabieWidth, tabieWidth]; 
[ ] 4— oocifit«rchang«o«fs.AppendAnchoredFrame( 
to: doc, 
type: table, 

anchoredFrameProps: ©props, 
content: table]; 
AddFileToOeskTop[doc]; - 
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<< Create table inside doc with specified number of rows and columns. The content will 
be the stri ng " abc. " > > 

BuildSimpleTable: proc [doc: oocinterchangeOefs.Ooc, rows, columns: cardinal] 
RETURNS [table: Oo<interchangeOefs.lnstance ^0<Klnterchang«0«fs.instanceNil] ■ { 
h: Tabi«lnt«rchangeOefs.Handle; 

contentString: xstring.ReaderBody xstring.FromSTRING["abc"L]; 
c: Tabi«int«rchangeOefs.Coiumnlnfo *- Heap.systemZone.NEw( 

Tabieint«rchangeO«fs.CoiumnlnfoSeq[columns]]; 
props: Tafal«lnterchang«0«fs.TablePropsRec [ 

name: nil, 

fiilinByRow: true, 

fixedRows: false, 

fixedColumns: true, 

numberOfCoiumns: columns, 

numberOfRows: rows, 

visibieHeader: true, 

repeatHeader: true. 

repeatTopCaption: true, 

repeatSottomCaption: true, 

borderline: [none, w1], 

dividerUne: [solid, w4], 

horizontalAlignment: center, 

headerVerticalAlignment: centered, 

topHeaderiWIargln: headerMargin, 

bottomHeaderMargIn: headerMargin, 

sortKeys: nil, 

sparel : 0]; 
FOR i: CARDINAL IN [O..columns) DO 

c[i1 *- TabieinterchangeO«fs.nullColumnlnfo; 

clij.width <-tableWidth; 

ENOLOOP; 

- start creating table 

h 4-Tabieint«rchangeOefs.StartTable[doc: doc, props: @props, c: c]; 

H«ap.systemZone.FREE[@cl; 

-- set row props and content 

h.rctopMargin ^ rowMargin; 

h.rcbottomMargin rowMargin; 

FOR i: CARDINAL IN [0..rOWS) DO 

FOR j: CARDINAL IN [O..COlumns) DO 

h.rc[jl4-[ 

subRows: nil, 
stngleLineHint: false, 
sparel : 0, 

content: [write(filllnTe)ctProc: FililnText,clientOata: @contentStringJ] ]; 

ENOLOOP; 

Tabi«interchang«Defs.AppendRow[h, h.rc]; 
ENDLOOP; 

RETURN [TablelnterchangeDefs.FlnishTable{h].table]; 
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< < call-back procedure that writes text into the Text field of the table. The text to write 
is specified by the ciientOata argument. > > 

FilllnText: Tabi«int«r€hangeO«fs.FilllnTextProc ■ { 

< <PROC [text: T«xtinterchangeOefs.Text, clientData: LONG pointer]; > > 

r: xstring.Reader *- NARROw[cllentData, xstring.Reader]; 
T«xtlnterdiangeOefs.AppendTextToText( 

to: text, 

text: r, 

textEndContext: xstring.unknownContext]; 

}; 

AddFiieToOeskTop: PROC(dOC: Do€lnterchange0«f$.0oc] » { 

docFile: NSFii«.Handle oocint«rchangeDefs.FinishCreation{@doc].docFi le; 

ref Doc: NSFii«. Reference a NSFiie.GetReference(docFile]; 

refOt: NSFiis.Reference » staro«sktop.GeKurrentOesktopFile[]; 

fiieOt: NSFii«.Handle » NSFii«.OpenByReference(refDt]; 

NSFii«.Move(docFile, fiieOt]; 

NSFiie.C!ose(fileOt]; 

NSFii«.Close(docFiie]; 

starO«sktop.AddReferenceToOesktop[refDoc] 

}; 

<<Menu Proc for Add To Table command. Just adds four new blank rows to selected 
table. >> 

AddToTabie: Mcnuoata.MenuProc > { 
h: Tabieinterchang«Oefs.Handle 4-NIL; 
table: OocinterchangeOefs.lnstance a 
TabieSeiectiono«fs.TabieFromSeiection(]; 
-if current selection is not a table, then return. Otherwise, 
-add new rows to it If doc Is not editable, then return. 
IF table ■ Doclnt«rchangeO«fs.inStanceNll THEN RETURN 
ELSE { 

h 4-Tabl«lnt«rchangeOefs.StartExistingTable( 

table: table, deieteExistingRows: false - catch error if doc is not editable 

! TablelnterchangeOefs.TableError a > GOTO Exit]; 
THROUGH [0..4) DO 

Tabl«lnterchangeDefs.AppendRow[h, h.rc]; 

endloop; 

}; 

[] 4- Tabi€lnt«r<hangeO«fs.Fini'shTable(h]; 

EXITS Exit a > null; 

}; 
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Init: PROC ■ { 

makeTable: xstring. Reader Body 4- xstring.FromSTRiNG["MakeTable"L]; 
addToTabie: xstring.ReaderBody <- xstring.FromSTRING['*AddToTabie"L]; 
Att0ntion.AddMenuitem[ 
M«nuOata.Createltem[ 

zone: Heap.systemZone, 

name: ©makeTable, 

proc: MakeOocument]]; 
Attention.AddMenuitem[ 
M«nuData.Createitem[ 

zone: H«ap.systemZone, 

name: @addToTabie, 

proc: AddToTabie]]; 

}; 

initG; 



}. 
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71.4 Index of Interface Items 



Item Page 

Append Row: proc 9 

Columnlnfo: type 4 

CoiumninfoRec: type 4 

CoiumninfoSeq: type 4 

ColumnsProc: type 10 

OefauitFontProps: proc 9 

DefauitParaProps: proc 9 

Enumerate: proc 10 

EnumerateSpecificRows: proc 10 

EnumProcs: type 10 

EnumProcsRec: type 10 

Error: signal 12 

ErrorType: type 12 

Fleldtype: type 6 

FinishTabie: proc 9 

Handle: type 7 

HeaderAiignment: type 3 

HeaderEntryRec: type 4 

Header! nfo: type 5 

HeaderlnfoSeq: type 5 

HorizontaiAiignment: type 3 

Line: type 3 

Linestyle: type 3 

Linewidth: type 3 

MaxTabieEIements: proc 9 

Object: type 7 

RowContent: type 7 

RowContentSeq: type 7 

RowEntryRec: type 8 

RowProc: type 10 

SkipChoices: type 7 

StartTabie: proc 2 

StartExistingTable: proc 8 

SubRows: type 8 

SubRowsRec: type 8 

TabieProc: type 10 

TabieProps: type 2 

TablePropsRec: type 2 

TableRows: type 10 

tabieRowsNii: TabieRows 10 

Vertical Alignment: type 3 
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66.1 Overview 

TableSeiectionOefs provides procedures to obtain the current selection as a table, or a 
selection of rows within a table. This interface is meant to be used in conjunction with 
TabieinterchangeOefs. 

66.2 Interface Items 

TabieFromSeiection: proc returns [Docinterchangeoefs-lnstance]; 

TableFromSeiection returns the current selection as an object of type instanceOefs.lnstance. 
The client will typically pass this value to Tableint«rchangeOefs.StartExistingTabie. 

TableRowsFromSeiection: proc returns [tr: Tabi€interchang«o«fs.TableRows]; 

TabieRowsFromSeiection returns the current selection as a series of rows in a table. The 
client will typically pass this . value as a parameter to 
TableinterchangeOefs-EnumerateSpecificRows. 

tablelarget: s«iection.Target; 

tableRowsTarget: s«i«ction.Target; 

TabieFromVaiue: proc[v: Seiection. Value] 
RETURNS [OoclnterchangeO«f S.I nstance] ; 

TabieRowsFromVaiue: proc[v: s«iection. Value] 
RETURNS [tr: Tabi«interchang«0«fs.TableROWS]; 

tableTarget, tableRowsTarget, TabieFromVaiue and TabieRowsFromVaiue are not 
currently implemented. 

GetHostOocAccess: proc [instance: Docinterchangeoefs.1 nstance] 
RETURNS [Access]; 

Access: type ■ machine dependent {readOnly(O), readWrite, (255)}; 
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Access specifies whether or not the document is in edit mode. 
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66.3 Index of Interface Items 

Item Page 

TabieFromSeiection: proc returns 
TabieFromValue: proc 
TableRowsFromSelection: proc 
TableRowsFromVaiue: proc 
tableRowsTarget: s<9i«ction 
tabteTarget: Selection 
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67.1 Overview 

TextlnterchangeDefs provides procedures to create and enumerate text that resides in 
locations that DocinterchangeOefs does not define. This interface is used by 
GraphicslnterchangeOefs to handle the content of nested text frames and by 
TabielnterchangeOefs to handle the content of header and row entries. 
TextlnterchangeDefs also provides procedures to handle the content of anchored text 
frames. All dimensions are in micas. 

67.2 Interface Items 



67.2.1 Data types 

The basic data structure of TextlnterchangeDefs is Text, which is a pointer to an opaque 
text containing object. 

Text: TYPE ■ LONG POINTER TO TextObject; 

TextObject: type; 

TFrameProps specify the properties of anchored text frames. Appending and enumerating 
text frames is covered later in this chapter. 

TFrameProps: TYPE ■ long pointer to TFramePropsRec; 

ReadonlyTFrameProps: TYPE ■ long pointer to readonly TFramePropsRec; 

TFramePropsRec: type ■ record ( 
innerMargin: long cardinal, 
name, description: xstring.Reader, 
sparel: long cardinal]; 

innerMargin is the uniform spacing between the text and the frame border. The client can 
vary the innerMargin from 0 to 7 pixels. This feature enables footnote frames that begin 
and end at the column margins. 
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TableSelectionOefs . t-i ' n .i ; 



name and desg'iptiorv;§r<^;.ti|et n^^i%a^ii4 df^jj^^ appears in the 

property sheet. -n- • ^ 

sparel is intended for future use. ^ ^ ; &7 rv i 

nullTFrameProps: TFramePropsRec a [ . 
innerMargin: 141, ^ ' *"..,.7+r f.-r,'.'.''.", 

name: nil, : i.r ^zr.^-:- r^--. ^ in^..n-i ••■.rKajaD-s^.:.,,.^;^- -.^ • v,.- ^r^- i.*;.--, • • 
description: NIL, 
sparel: 0]; 

nullTFrameProps provides default initialization values for the TFramePropsRec 

67.2.2 Creating an Anchored 'T^sa'FVaMe-''V -"-^"^^ 

;'^*'jT.H'!f':'»f;r,.,r:-.';.;:-f>'-. if-'. 

StartTextlnAnchoredFrame is used to begin appending text to the body of an anchored te.xt 
frame. After an anchored text frame has been appended to a document via 
OocinterchangeOefs.AppendAnchoredFrame, StartTextlnAnchoredFrame niky be called to 
permit text to be appepded^tp itf i^od^^^^ „ . . 

StartTextlnAnchoredFrame: PROC [ 
doc:0oclnterchange0«fs.0oc, 

anchoredFrame: Oocint«rchange0efs.lnstance, „ - ,1' . 

props: Readonly TFrameProps] * j^,, ^ , - 

RETURNS [text: Textl; . . , „ , 1 ... 

^. cdociathedocumejxtcontiaiping thej^^ , 

anchoredFrame is the Docinterchangeoefs. instance returned by the call to 
e;'0Q£int«rcl)ang«09fs.>Akppend/^nchpredFrar^^^^ .kc.,-^^,... .-c-*- 

67.2.3 Append Operations 

The following append* procedures are similar to the ones found in OocinterchangeOefs; 
the only diflerence is that these proc^'Hiiifes append to 'text objects obtained from 
StartTextlnAnchoredFrame: 7' ^^::jsc:vT---^;p.7r r-. . ' 

AppendCharToText: proc [ " " ' ■ - rn^i-;,, ^'^^r, 

tO:TeXt. ' ■ -.^^OO-' • -'-■^v.^•>-. ' ^ 

.4,. char: xchar.Character, 

' ■ ' ' ' ' "fbntWojjs:"^^ 

nToAppend: CARDINAL 1]; 

AppendFieidToText: PROC [ . C/; , : j - 

to: Text, »n?u-. . 

fieidProps: Ooclnt«rchangePropsbefi;ReadonfyFieldPropS, 
fontProps: oocinterchangePropsOefs.ReadoniyFontProps 4<-nil] 
RETURNS [fleld:Doclnt«rchangeOefs.Fleld]; 



; ' AppeddNeWParadrapHToText: PROC I 



paraProps: oocint«rchangePropsOefs.ReadonlyParaProps ^ nil. 
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nToAppend: CAROINAI.4- 1]; it^r;;: vnyco jq 

AppendTextToText: proc ( '^■^'^ - ' '-^^ ^-ifb^r-i^m I' ^isqe 

to: Text, 

text: xstring.Reader. > ^ ^^^^^-^■•'"si'rse^^-i' '2ao-«*-*r'<!?}-^nSkir, 

textEndContext: xstrin9.Context, - ' '•nD^ i^vnanru 

fontProps: Docint«rdiangePropsOefs.ReadoniyFontProps nil]; ^^'Ti xn 

AppendTileToText: PROC [ : ' : l ytf^c?;? 

to: Text, , , 

typ^:'Atmii.AtbiM/'' r:-:^*'^}.;; ^oLUb-in zz;v^*im>..s<7\;ii'-. 

data : long pointer nil, 

fontProps: Oo<lnterchang«Prop$Defs,ReadonlyFoot^lg)ps,4|nNl4,.^,,^ „g ^jnr-Fi*^:) 
returns [tile: Oocint«r€hangeO«fs,Tile]; 

67.2.4 EnumeraAoii ' '''"^■'*' -^-•^'^"■-^i ''^^-'i^ ^mt-^ 

To extract the content of a text object, cli^Sts tSall lnullrtciratMT^xt; - - ; 
EnumerateText: PROC [ ^ jd)^^. ->tf>n>f:/i: ixt-'Tnpic 

text: Text, .:'f'^G.r(^.CB*D;-«.nr,f-'r,:>,;,c 

procs: TextEnumProcs, ^y>r*i:j-gnLj*&OfV ►^r;5t^?.mrroi:- :/-.'m»--^^t^fi-"',D!' a^is 
dientData: LONG POINTER <-nil1 ^i^t^^'^ii»m£,v: -'vu^oD^.^r .e«Dt^ 

RETURNS [dataSkipped: boolean]; f^^^ t >wviniyi 

procs is a pointeFl&^k' Fecdr^'''wln^f^^^ these 
enumerate the various kinds of structures that can be found in text. 

ciientOata is a client defined argui^eht that^AiirlB^b^^^ call-back 
procedures. 

TextEnumProcs: type ■ long pointer to TextEnumProcsRecord; " ' " ^ * ^' 

TextEnumProcsRecord;, TYPE ?,.i!^cqRpr, ^£.^5.; n-.. ,^.,„,.. 

fieldProc: Docint«rchangePropsOefs.FieldProc <- Nili,. „ j^,, , 
newParagraphProc: oocinterchang«PropsD«fs.NewParagraphpfoc 4^ riiL. 
textPrOC: Oo€lnt«rchang«PropsOefs.TextPrOC 4-NIL, y_ 1 i^T i - cc / 

tileProc: Oo<lnt«ri:hangePropsO«fs.T]ieProC4~NIL]; 



.0 

, '1:: ,' . "'S^r;,,' 

TextForAnchoredFra^i;i^.f vtf^used w|tenj^cU^n$^^^ tp je^!^mer.|t^ ,lj|^e.l^ of an anchored 

text frame. , '■ f wr/.*r''"!'?C, J 

TextForAnchoredFrame: PROC [ 

doc: Doclnterchang«PropsOefs.Doc, ^ ?, 

content: Doelnter<hang«Prop!iDffsJnstan^;p, v^9,^p,^,~,,,,,^,^. , j 

props: TFramePropslt.,o^.-rc-.v- -./w .^^-,',0.;.-..^^..' ' " ■^^V .-V^.- 
RETURNS [text: Text]; ^ , , . ^, 

doc is the document containing the anchored text-fran^^to .e^\^nci|r^ is the 

value passed to the OcklntarchangeOefs.AnchoredFrameProc. The te^^ c^bject't is returned 
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may be passed to EnumerateText. After enumerating the text, the client must call 
ReieaseText on the text object returned by TextForAnchore^JFrafie., , , - ^ ^ , ^ 

TextForAnchoredFrame fills ie^^^rpps with text specific properties of the fran\e, , 

67.2.3 Releasing Text 

The client should release the text object after calling StartTextlnAnchoredFrame or 
TextForAnchoredFrame. 

ReieaseText: proc [textPtr: long pointer to Text]; 
67.3 Example 

The proper sequence of calls to append an anchored text frame having content is: 
props: T«xtlnterchangeD«fs.TFramePropsRec <~ [...]; 

[anchoredFrame, ...] 4-oocinterchang«oefs.AppendAnchoredFrame[to: doc. type: text, ...]; 
text 4-T«xtinterdiang«D«fs.StartText[doc, anchoredFrame, ©props]; 
TextintarchangeD«fs.AppendTextToText(text, reader, ...]; 
TextinterchangeOef s.ReieaseText(@text] ; 

It is not mandatory that the client call StartTextlnAnclioredFrame after appending an 
anchored frame. Failing to call StartTextinAnchoredFrame simply means that the 
anchored text frame will be empty, except for one new paragraph character that has 
default paragraph and font properties. Note that if the client does not call 
StartTextlnAnchoredFrame, then the client should not call ReieaseText. 
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-^iewPaint PKograiiuner*s.MaiiMal_ .._ , ^,„ . . O # 



67.3 Index of Interface Ifgafe^sv>.-.;..nA io^fx*.T vd Dsniyitrr Jna^ao jxsl no JjffT»e&»Ss^l! 



,^0biis»-; 7^?*tjT-,*H circs'* b^^^ot^^,^l■5?i^-;>.vftr1»•t^,,rt^^^ 
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